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 Detect_Blocking::
122 * Pragma Elaboration_Checks::
124 * Pragma Export_Exception::
125 * Pragma Export_Function::
126 * Pragma Export_Object::
127 * Pragma Export_Procedure::
128 * Pragma Export_Value::
129 * Pragma Export_Valued_Procedure::
130 * Pragma Extend_System::
132 * Pragma External_Name_Casing::
133 * Pragma Finalize_Storage_Only::
134 * Pragma Float_Representation::
136 * Pragma Import_Exception::
137 * Pragma Import_Function::
138 * Pragma Import_Object::
139 * Pragma Import_Procedure::
140 * Pragma Import_Valued_Procedure::
141 * Pragma Initialize_Scalars::
142 * Pragma Inline_Always::
143 * Pragma Inline_Generic::
145 * Pragma Interface_Name::
146 * Pragma Interrupt_Handler::
147 * Pragma Interrupt_State::
148 * Pragma Keep_Names::
151 * Pragma Linker_Alias::
152 * Pragma Linker_Constructor::
153 * Pragma Linker_Destructor::
154 * Pragma Linker_Section::
155 * Pragma Long_Float::
156 * Pragma Machine_Attribute::
157 * Pragma Main_Storage::
159 * Pragma Normalize_Scalars::
160 * Pragma Obsolescent::
162 * Pragma Persistent_BSS::
164 * Pragma Profile (Ravenscar)::
165 * Pragma Profile (Restricted)::
166 * Pragma Propagate_Exceptions::
167 * Pragma Psect_Object::
168 * Pragma Pure_Function::
169 * Pragma Restriction_Warnings::
170 * Pragma Source_File_Name::
171 * Pragma Source_File_Name_Project::
172 * Pragma Source_Reference::
173 * Pragma Stream_Convert::
174 * Pragma Style_Checks::
176 * Pragma Suppress_All::
177 * Pragma Suppress_Exception_Locations::
178 * Pragma Suppress_Initialization::
181 * Pragma Task_Storage::
182 * Pragma Thread_Body::
183 * Pragma Time_Slice::
185 * Pragma Unchecked_Union::
186 * Pragma Unimplemented_Unit::
187 * Pragma Universal_Data::
188 * Pragma Unreferenced::
189 * Pragma Unreserve_All_Interrupts::
190 * Pragma Unsuppress::
191 * Pragma Use_VADS_Size::
192 * Pragma Validity_Checks::
195 * Pragma Weak_External::
197 Implementation Defined Attributes
207 * Default_Bit_Order::
215 * Has_Access_Values::
216 * Has_Discriminants::
222 * Max_Interrupt_Priority::
224 * Maximum_Alignment::
228 * Passed_By_Reference::
239 * Unconstrained_Array::
240 * Universal_Literal_String::
241 * Unrestricted_Access::
247 The Implementation of Standard I/O
249 * Standard I/O Packages::
255 * Wide_Wide_Text_IO::
259 * Operations on C Streams::
260 * Interfacing to C Streams::
264 * Ada.Characters.Latin_9 (a-chlat9.ads)::
265 * Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
266 * Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
267 * Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads)::
268 * Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads)::
269 * Ada.Command_Line.Remove (a-colire.ads)::
270 * Ada.Command_Line.Environment (a-colien.ads)::
271 * Ada.Direct_IO.C_Streams (a-diocst.ads)::
272 * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
273 * Ada.Exceptions.Traceback (a-exctra.ads)::
274 * Ada.Sequential_IO.C_Streams (a-siocst.ads)::
275 * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
276 * Ada.Strings.Unbounded.Text_IO (a-suteio.ads)::
277 * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
278 * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
279 * Ada.Text_IO.C_Streams (a-tiocst.ads)::
280 * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
281 * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
282 * GNAT.Array_Split (g-arrspl.ads)::
283 * GNAT.AWK (g-awk.ads)::
284 * GNAT.Bounded_Buffers (g-boubuf.ads)::
285 * GNAT.Bounded_Mailboxes (g-boumai.ads)::
286 * GNAT.Bubble_Sort (g-bubsor.ads)::
287 * GNAT.Bubble_Sort_A (g-busora.ads)::
288 * GNAT.Bubble_Sort_G (g-busorg.ads)::
289 * GNAT.Calendar (g-calend.ads)::
290 * GNAT.Calendar.Time_IO (g-catiio.ads)::
291 * GNAT.Case_Util (g-casuti.ads)::
292 * GNAT.CGI (g-cgi.ads)::
293 * GNAT.CGI.Cookie (g-cgicoo.ads)::
294 * GNAT.CGI.Debug (g-cgideb.ads)::
295 * GNAT.Command_Line (g-comlin.ads)::
296 * GNAT.Compiler_Version (g-comver.ads)::
297 * GNAT.Ctrl_C (g-ctrl_c.ads)::
298 * GNAT.CRC32 (g-crc32.ads)::
299 * GNAT.Current_Exception (g-curexc.ads)::
300 * GNAT.Debug_Pools (g-debpoo.ads)::
301 * GNAT.Debug_Utilities (g-debuti.ads)::
302 * GNAT.Directory_Operations (g-dirope.ads)::
303 * GNAT.Dynamic_HTables (g-dynhta.ads)::
304 * GNAT.Dynamic_Tables (g-dyntab.ads)::
305 * GNAT.Exception_Actions (g-excact.ads)::
306 * GNAT.Exception_Traces (g-exctra.ads)::
307 * GNAT.Exceptions (g-except.ads)::
308 * GNAT.Expect (g-expect.ads)::
309 * GNAT.Float_Control (g-flocon.ads)::
310 * GNAT.Heap_Sort (g-heasor.ads)::
311 * GNAT.Heap_Sort_A (g-hesora.ads)::
312 * GNAT.Heap_Sort_G (g-hesorg.ads)::
313 * GNAT.HTable (g-htable.ads)::
314 * GNAT.IO (g-io.ads)::
315 * GNAT.IO_Aux (g-io_aux.ads)::
316 * GNAT.Lock_Files (g-locfil.ads)::
317 * GNAT.MD5 (g-md5.ads)::
318 * GNAT.Memory_Dump (g-memdum.ads)::
319 * GNAT.Most_Recent_Exception (g-moreex.ads)::
320 * GNAT.OS_Lib (g-os_lib.ads)::
321 * GNAT.Perfect_Hash_Generators (g-pehage.ads)::
322 * GNAT.Regexp (g-regexp.ads)::
323 * GNAT.Registry (g-regist.ads)::
324 * GNAT.Regpat (g-regpat.ads)::
325 * GNAT.Secondary_Stack_Info (g-sestin.ads)::
326 * GNAT.Semaphores (g-semaph.ads)::
327 * GNAT.Signals (g-signal.ads)::
328 * GNAT.Sockets (g-socket.ads)::
329 * GNAT.Source_Info (g-souinf.ads)::
330 * GNAT.Spell_Checker (g-speche.ads)::
331 * GNAT.Spitbol.Patterns (g-spipat.ads)::
332 * GNAT.Spitbol (g-spitbo.ads)::
333 * GNAT.Spitbol.Table_Boolean (g-sptabo.ads)::
334 * GNAT.Spitbol.Table_Integer (g-sptain.ads)::
335 * GNAT.Spitbol.Table_VString (g-sptavs.ads)::
336 * GNAT.Strings (g-string.ads)::
337 * GNAT.String_Split (g-strspl.ads)::
338 * GNAT.Table (g-table.ads)::
339 * GNAT.Task_Lock (g-tasloc.ads)::
340 * GNAT.Threads (g-thread.ads)::
341 * GNAT.Traceback (g-traceb.ads)::
342 * GNAT.Traceback.Symbolic (g-trasym.ads)::
343 * GNAT.Wide_String_Split (g-wistsp.ads)::
344 * GNAT.Wide_Wide_String_Split (g-zistsp.ads)::
345 * Interfaces.C.Extensions (i-cexten.ads)::
346 * Interfaces.C.Streams (i-cstrea.ads)::
347 * Interfaces.CPP (i-cpp.ads)::
348 * Interfaces.Os2lib (i-os2lib.ads)::
349 * Interfaces.Os2lib.Errors (i-os2err.ads)::
350 * Interfaces.Os2lib.Synchronization (i-os2syn.ads)::
351 * Interfaces.Os2lib.Threads (i-os2thr.ads)::
352 * Interfaces.Packed_Decimal (i-pacdec.ads)::
353 * Interfaces.VxWorks (i-vxwork.ads)::
354 * Interfaces.VxWorks.IO (i-vxwoio.ads)::
355 * System.Address_Image (s-addima.ads)::
356 * System.Assertions (s-assert.ads)::
357 * System.Memory (s-memory.ads)::
358 * System.Partition_Interface (s-parint.ads)::
359 * System.Restrictions (s-restri.ads)::
360 * System.Rident (s-rident.ads)::
361 * System.Task_Info (s-tasinf.ads)::
362 * System.Wch_Cnv (s-wchcnv.ads)::
363 * System.Wch_Con (s-wchcon.ads)::
367 * Text_IO Stream Pointer Positioning::
368 * Text_IO Reading and Writing Non-Regular Files::
370 * Treating Text_IO Files as Streams::
371 * Text_IO Extensions::
372 * Text_IO Facilities for Unbounded Strings::
376 * Wide_Text_IO Stream Pointer Positioning::
377 * Wide_Text_IO Reading and Writing Non-Regular Files::
381 * Wide_Wide_Text_IO Stream Pointer Positioning::
382 * Wide_Wide_Text_IO Reading and Writing Non-Regular Files::
384 Interfacing to Other Languages
387 * Interfacing to C++::
388 * Interfacing to COBOL::
389 * Interfacing to Fortran::
390 * Interfacing to non-GNAT Ada code::
392 Specialized Needs Annexes
394 Implementation of Specific Ada Features
395 * Machine Code Insertions::
396 * GNAT Implementation of Tasking::
397 * GNAT Implementation of Shared Passive Packages::
398 * Code Generation for Array Aggregates::
399 * The Size of Discriminated Records with Default Discriminants::
401 Project File Reference
405 GNU Free Documentation License
412 @node About This Guide
413 @unnumbered About This Guide
417 This manual contains useful information in writing programs using the
418 GNAT compiler. It includes information on implementation dependent
419 characteristics of GNAT, including all the information required by Annex
425 This manual contains useful information in writing programs using the
426 GNAT Pro compiler. It includes information on implementation dependent
427 characteristics of GNAT Pro, including all the information required by Annex
431 Ada 95 is designed to be highly portable.
432 In general, a program will have the same effect even when compiled by
433 different compilers on different platforms.
434 However, since Ada 95 is designed to be used in a
435 wide variety of applications, it also contains a number of system
436 dependent features to be used in interfacing to the external world.
437 @cindex Implementation-dependent features
440 Note: Any program that makes use of implementation-dependent features
441 may be non-portable. You should follow good programming practice and
442 isolate and clearly document any sections of your program that make use
443 of these features in a non-portable manner.
446 For ease of exposition, ``GNAT Pro'' will be referred to simply as
447 ``GNAT'' in the remainder of this document.
451 * What This Reference Manual Contains::
453 * Related Information::
456 @node What This Reference Manual Contains
457 @unnumberedsec What This Reference Manual Contains
460 This reference manual contains the following chapters:
464 @ref{Implementation Defined Pragmas}, lists GNAT implementation-dependent
465 pragmas, which can be used to extend and enhance the functionality of the
469 @ref{Implementation Defined Attributes}, lists GNAT
470 implementation-dependent attributes which can be used to extend and
471 enhance the functionality of the compiler.
474 @ref{Implementation Advice}, provides information on generally
475 desirable behavior which are not requirements that all compilers must
476 follow since it cannot be provided on all systems, or which may be
477 undesirable on some systems.
480 @ref{Implementation Defined Characteristics}, provides a guide to
481 minimizing implementation dependent features.
484 @ref{Intrinsic Subprograms}, describes the intrinsic subprograms
485 implemented by GNAT, and how they can be imported into user
486 application programs.
489 @ref{Representation Clauses and Pragmas}, describes in detail the
490 way that GNAT represents data, and in particular the exact set
491 of representation clauses and pragmas that is accepted.
494 @ref{Standard Library Routines}, provides a listing of packages and a
495 brief description of the functionality that is provided by Ada's
496 extensive set of standard library routines as implemented by GNAT@.
499 @ref{The Implementation of Standard I/O}, details how the GNAT
500 implementation of the input-output facilities.
503 @ref{The GNAT Library}, is a catalog of packages that complement
504 the Ada predefined library.
507 @ref{Interfacing to Other Languages}, describes how programs
508 written in Ada using GNAT can be interfaced to other programming
511 @ref{Specialized Needs Annexes}, describes the GNAT implementation of all
512 of the specialized needs annexes.
515 @ref{Implementation of Specific Ada Features}, discusses issues related
516 to GNAT's implementation of machine code insertions, tasking, and several
520 @ref{Project File Reference}, presents the syntax and semantics
524 @ref{Obsolescent Features} documents implementation dependent features,
525 including pragmas and attributes, which are considered obsolescent, since
526 there are other preferred ways of achieving the same results. These
527 obsolescent forms are retained for backwards compatibility.
531 @cindex Ada 95 ISO/ANSI Standard
533 This reference manual assumes that you are familiar with Ada 95
534 language, as described in the International Standard
535 ANSI/ISO/IEC-8652:1995, Jan 1995.
538 @unnumberedsec Conventions
539 @cindex Conventions, typographical
540 @cindex Typographical conventions
543 Following are examples of the typographical and graphic conventions used
548 @code{Functions}, @code{utility program names}, @code{standard names},
555 @file{File Names}, @samp{button names}, and @samp{field names}.
564 [optional information or parameters]
567 Examples are described by text
569 and then shown this way.
574 Commands that are entered by the user are preceded in this manual by the
575 characters @samp{$ } (dollar sign followed by space). If your system uses this
576 sequence as a prompt, then the commands will appear exactly as you see them
577 in the manual. If your system uses some other prompt, then the command will
578 appear with the @samp{$} replaced by whatever prompt character you are using.
580 @node Related Information
581 @unnumberedsec Related Information
583 See the following documents for further information on GNAT:
587 @cite{GNAT User's Guide}, which provides information on how to use
588 the GNAT compiler system.
591 @cite{Ada 95 Reference Manual}, which contains all reference
592 material for the Ada 95 programming language.
595 @cite{Ada 95 Annotated Reference Manual}, which is an annotated version
596 of the standard reference manual cited above. The annotations describe
597 detailed aspects of the design decision, and in particular contain useful
598 sections on Ada 83 compatibility.
601 @cite{DEC Ada, Technical Overview and Comparison on DIGITAL Platforms},
602 which contains specific information on compatibility between GNAT and
606 @cite{DEC Ada, Language Reference Manual, part number AA-PYZAB-TK} which
607 describes in detail the pragmas and attributes provided by the DEC Ada 83
612 @node Implementation Defined Pragmas
613 @chapter Implementation Defined Pragmas
616 Ada 95 defines a set of pragmas that can be used to supply additional
617 information to the compiler. These language defined pragmas are
618 implemented in GNAT and work as described in the Ada 95 Reference
621 In addition, Ada 95 allows implementations to define additional pragmas
622 whose meaning is defined by the implementation. GNAT provides a number
623 of these implementation-dependent pragmas which can be used to extend
624 and enhance the functionality of the compiler. This section of the GNAT
625 Reference Manual describes these additional pragmas.
627 Note that any program using these pragmas may not be portable to other
628 compilers (although GNAT implements this set of pragmas on all
629 platforms). Therefore if portability to other compilers is an important
630 consideration, the use of these pragmas should be minimized.
633 * Pragma Abort_Defer::
640 * Pragma C_Pass_By_Copy::
642 * Pragma Common_Object::
643 * Pragma Compile_Time_Warning::
644 * Pragma Complex_Representation::
645 * Pragma Component_Alignment::
646 * Pragma Convention_Identifier::
648 * Pragma CPP_Constructor::
649 * Pragma CPP_Virtual::
650 * Pragma CPP_Vtable::
652 * Pragma Detect_Blocking::
653 * Pragma Elaboration_Checks::
655 * Pragma Export_Exception::
656 * Pragma Export_Function::
657 * Pragma Export_Object::
658 * Pragma Export_Procedure::
659 * Pragma Export_Value::
660 * Pragma Export_Valued_Procedure::
661 * Pragma Extend_System::
663 * Pragma External_Name_Casing::
664 * Pragma Finalize_Storage_Only::
665 * Pragma Float_Representation::
667 * Pragma Import_Exception::
668 * Pragma Import_Function::
669 * Pragma Import_Object::
670 * Pragma Import_Procedure::
671 * Pragma Import_Valued_Procedure::
672 * Pragma Initialize_Scalars::
673 * Pragma Inline_Always::
674 * Pragma Inline_Generic::
676 * Pragma Interface_Name::
677 * Pragma Interrupt_Handler::
678 * Pragma Interrupt_State::
679 * Pragma Keep_Names::
682 * Pragma Linker_Alias::
683 * Pragma Linker_Constructor::
684 * Pragma Linker_Destructor::
685 * Pragma Linker_Section::
686 * Pragma Long_Float::
687 * Pragma Machine_Attribute::
688 * Pragma Main_Storage::
690 * Pragma Normalize_Scalars::
691 * Pragma Obsolescent::
693 * Pragma Persistent_BSS::
695 * Pragma Profile (Ravenscar)::
696 * Pragma Profile (Restricted)::
697 * Pragma Propagate_Exceptions::
698 * Pragma Psect_Object::
699 * Pragma Pure_Function::
700 * Pragma Restriction_Warnings::
701 * Pragma Source_File_Name::
702 * Pragma Source_File_Name_Project::
703 * Pragma Source_Reference::
704 * Pragma Stream_Convert::
705 * Pragma Style_Checks::
707 * Pragma Suppress_All::
708 * Pragma Suppress_Exception_Locations::
709 * Pragma Suppress_Initialization::
712 * Pragma Task_Storage::
713 * Pragma Thread_Body::
714 * Pragma Time_Slice::
716 * Pragma Unchecked_Union::
717 * Pragma Unimplemented_Unit::
718 * Pragma Universal_Data::
719 * Pragma Unreferenced::
720 * Pragma Unreserve_All_Interrupts::
721 * Pragma Unsuppress::
722 * Pragma Use_VADS_Size::
723 * Pragma Validity_Checks::
726 * Pragma Weak_External::
729 @node Pragma Abort_Defer
730 @unnumberedsec Pragma Abort_Defer
732 @cindex Deferring aborts
740 This pragma must appear at the start of the statement sequence of a
741 handled sequence of statements (right after the @code{begin}). It has
742 the effect of deferring aborts for the sequence of statements (but not
743 for the declarations or handlers, if any, associated with this statement
747 @unnumberedsec Pragma Ada_83
756 A configuration pragma that establishes Ada 83 mode for the unit to
757 which it applies, regardless of the mode set by the command line
758 switches. In Ada 83 mode, GNAT attempts to be as compatible with
759 the syntax and semantics of Ada 83, as defined in the original Ada
760 83 Reference Manual as possible. In particular, the new Ada 95
761 keywords are not recognized, optional package bodies are allowed,
762 and generics may name types with unknown discriminants without using
763 the @code{(<>)} notation. In addition, some but not all of the additional
764 restrictions of Ada 83 are enforced.
766 Ada 83 mode is intended for two purposes. Firstly, it allows existing
767 legacy Ada 83 code to be compiled and adapted to GNAT with less effort.
768 Secondly, it aids in keeping code backwards compatible with Ada 83.
769 However, there is no guarantee that code that is processed correctly
770 by GNAT in Ada 83 mode will in fact compile and execute with an Ada
771 83 compiler, since GNAT does not enforce all the additional checks
775 @unnumberedsec Pragma Ada_95
784 A configuration pragma that establishes Ada 95 mode for the unit to which
785 it applies, regardless of the mode set by the command line switches.
786 This mode is set automatically for the @code{Ada} and @code{System}
787 packages and their children, so you need not specify it in these
788 contexts. This pragma is useful when writing a reusable component that
789 itself uses Ada 95 features, but which is intended to be usable from
790 either Ada 83 or Ada 95 programs.
793 @unnumberedsec Pragma Ada_05
802 A configuration pragma that establishes Ada 2005 mode for the unit to which
803 it applies, regardless of the mode set by the command line switches.
804 This mode is set automatically for the @code{Ada} and @code{System}
805 packages and their children, so you need not specify it in these
806 contexts. This pragma is useful when writing a reusable component that
807 itself uses Ada 2005 features, but which is intended to be usable from
808 either Ada 83 or Ada 95 programs.
810 @node Pragma Annotate
811 @unnumberedsec Pragma Annotate
816 pragma Annotate (IDENTIFIER @{, ARG@});
818 ARG ::= NAME | EXPRESSION
822 This pragma is used to annotate programs. @var{identifier} identifies
823 the type of annotation. GNAT verifies this is an identifier, but does
824 not otherwise analyze it. The @var{arg} argument
825 can be either a string literal or an
826 expression. String literals are assumed to be of type
827 @code{Standard.String}. Names of entities are simply analyzed as entity
828 names. All other expressions are analyzed as expressions, and must be
831 The analyzed pragma is retained in the tree, but not otherwise processed
832 by any part of the GNAT compiler. This pragma is intended for use by
833 external tools, including ASIS@.
836 @unnumberedsec Pragma Assert
843 [, static_string_EXPRESSION]);
847 The effect of this pragma depends on whether the corresponding command
848 line switch is set to activate assertions. The pragma expands into code
849 equivalent to the following:
852 if assertions-enabled then
853 if not boolean_EXPRESSION then
854 System.Assertions.Raise_Assert_Failure
861 The string argument, if given, is the message that will be associated
862 with the exception occurrence if the exception is raised. If no second
863 argument is given, the default message is @samp{@var{file}:@var{nnn}},
864 where @var{file} is the name of the source file containing the assert,
865 and @var{nnn} is the line number of the assert. A pragma is not a
866 statement, so if a statement sequence contains nothing but a pragma
867 assert, then a null statement is required in addition, as in:
872 pragma Assert (K > 3, "Bad value for K");
878 Note that, as with the @code{if} statement to which it is equivalent, the
879 type of the expression is either @code{Standard.Boolean}, or any type derived
880 from this standard type.
882 If assertions are disabled (switch @code{-gnata} not used), then there
883 is no effect (and in particular, any side effects from the expression
884 are suppressed). More precisely it is not quite true that the pragma
885 has no effect, since the expression is analyzed, and may cause types
886 to be frozen if they are mentioned here for the first time.
888 If assertions are enabled, then the given expression is tested, and if
889 it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called
890 which results in the raising of @code{Assert_Failure} with the given message.
892 If the boolean expression has side effects, these side effects will turn
893 on and off with the setting of the assertions mode, resulting in
894 assertions that have an effect on the program. You should generally
895 avoid side effects in the expression arguments of this pragma. However,
896 the expressions are analyzed for semantic correctness whether or not
897 assertions are enabled, so turning assertions on and off cannot affect
898 the legality of a program.
900 @node Pragma Ast_Entry
901 @unnumberedsec Pragma Ast_Entry
907 pragma AST_Entry (entry_IDENTIFIER);
911 This pragma is implemented only in the OpenVMS implementation of GNAT@. The
912 argument is the simple name of a single entry; at most one @code{AST_Entry}
913 pragma is allowed for any given entry. This pragma must be used in
914 conjunction with the @code{AST_Entry} attribute, and is only allowed after
915 the entry declaration and in the same task type specification or single task
916 as the entry to which it applies. This pragma specifies that the given entry
917 may be used to handle an OpenVMS asynchronous system trap (@code{AST})
918 resulting from an OpenVMS system service call. The pragma does not affect
919 normal use of the entry. For further details on this pragma, see the
920 DEC Ada Language Reference Manual, section 9.12a.
922 @node Pragma C_Pass_By_Copy
923 @unnumberedsec Pragma C_Pass_By_Copy
924 @cindex Passing by copy
925 @findex C_Pass_By_Copy
929 pragma C_Pass_By_Copy
930 ([Max_Size =>] static_integer_EXPRESSION);
934 Normally the default mechanism for passing C convention records to C
935 convention subprograms is to pass them by reference, as suggested by RM
936 B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change
937 this default, by requiring that record formal parameters be passed by
938 copy if all of the following conditions are met:
942 The size of the record type does not exceed@*@var{static_integer_expression}.
944 The record type has @code{Convention C}.
946 The formal parameter has this record type, and the subprogram has a
947 foreign (non-Ada) convention.
951 If these conditions are met the argument is passed by copy, i.e.@: in a
952 manner consistent with what C expects if the corresponding formal in the
953 C prototype is a struct (rather than a pointer to a struct).
955 You can also pass records by copy by specifying the convention
956 @code{C_Pass_By_Copy} for the record type, or by using the extended
957 @code{Import} and @code{Export} pragmas, which allow specification of
958 passing mechanisms on a parameter by parameter basis.
961 @unnumberedsec Pragma Comment
967 pragma Comment (static_string_EXPRESSION);
971 This is almost identical in effect to pragma @code{Ident}. It allows the
972 placement of a comment into the object file and hence into the
973 executable file if the operating system permits such usage. The
974 difference is that @code{Comment}, unlike @code{Ident}, has
975 no limitations on placement of the pragma (it can be placed
976 anywhere in the main source unit), and if more than one pragma
977 is used, all comments are retained.
979 @node Pragma Common_Object
980 @unnumberedsec Pragma Common_Object
981 @findex Common_Object
986 pragma Common_Object (
987 [Internal =>] local_NAME,
988 [, [External =>] EXTERNAL_SYMBOL]
989 [, [Size =>] EXTERNAL_SYMBOL] );
993 | static_string_EXPRESSION
997 This pragma enables the shared use of variables stored in overlaid
998 linker areas corresponding to the use of @code{COMMON}
999 in Fortran. The single
1000 object @var{local_NAME} is assigned to the area designated by
1001 the @var{External} argument.
1002 You may define a record to correspond to a series
1003 of fields. The @var{size} argument
1004 is syntax checked in GNAT, but otherwise ignored.
1006 @code{Common_Object} is not supported on all platforms. If no
1007 support is available, then the code generator will issue a message
1008 indicating that the necessary attribute for implementation of this
1009 pragma is not available.
1011 @node Pragma Compile_Time_Warning
1012 @unnumberedsec Pragma Compile_Time_Warning
1013 @findex Compile_Time_Warning
1017 @smallexample @c ada
1018 pragma Compile_Time_Warning
1019 (boolean_EXPRESSION, static_string_EXPRESSION);
1023 This pragma can be used to generate additional compile time warnings. It
1024 is particularly useful in generics, where warnings can be issued for
1025 specific problematic instantiations. The first parameter is a boolean
1026 expression. The pragma is effective only if the value of this expression
1027 is known at compile time, and has the value True. The set of expressions
1028 whose values are known at compile time includes all static boolean
1029 expressions, and also other values which the compiler can determine
1030 at compile time (e.g. the size of a record type set by an explicit
1031 size representation clause, or the value of a variable which was
1032 initialized to a constant and is known not to have been modified).
1033 If these conditions are met, a warning message is generated using
1034 the value given as the second argument. This string value may contain
1035 embedded ASCII.LF characters to break the message into multiple lines.
1037 @node Pragma Complex_Representation
1038 @unnumberedsec Pragma Complex_Representation
1039 @findex Complex_Representation
1043 @smallexample @c ada
1044 pragma Complex_Representation
1045 ([Entity =>] local_NAME);
1049 The @var{Entity} argument must be the name of a record type which has
1050 two fields of the same floating-point type. The effect of this pragma is
1051 to force gcc to use the special internal complex representation form for
1052 this record, which may be more efficient. Note that this may result in
1053 the code for this type not conforming to standard ABI (application
1054 binary interface) requirements for the handling of record types. For
1055 example, in some environments, there is a requirement for passing
1056 records by pointer, and the use of this pragma may result in passing
1057 this type in floating-point registers.
1059 @node Pragma Component_Alignment
1060 @unnumberedsec Pragma Component_Alignment
1061 @cindex Alignments of components
1062 @findex Component_Alignment
1066 @smallexample @c ada
1067 pragma Component_Alignment (
1068 [Form =>] ALIGNMENT_CHOICE
1069 [, [Name =>] type_local_NAME]);
1071 ALIGNMENT_CHOICE ::=
1079 Specifies the alignment of components in array or record types.
1080 The meaning of the @var{Form} argument is as follows:
1083 @findex Component_Size
1084 @item Component_Size
1085 Aligns scalar components and subcomponents of the array or record type
1086 on boundaries appropriate to their inherent size (naturally
1087 aligned). For example, 1-byte components are aligned on byte boundaries,
1088 2-byte integer components are aligned on 2-byte boundaries, 4-byte
1089 integer components are aligned on 4-byte boundaries and so on. These
1090 alignment rules correspond to the normal rules for C compilers on all
1091 machines except the VAX@.
1093 @findex Component_Size_4
1094 @item Component_Size_4
1095 Naturally aligns components with a size of four or fewer
1096 bytes. Components that are larger than 4 bytes are placed on the next
1099 @findex Storage_Unit
1101 Specifies that array or record components are byte aligned, i.e.@:
1102 aligned on boundaries determined by the value of the constant
1103 @code{System.Storage_Unit}.
1107 Specifies that array or record components are aligned on default
1108 boundaries, appropriate to the underlying hardware or operating system or
1109 both. For OpenVMS VAX systems, the @code{Default} choice is the same as
1110 the @code{Storage_Unit} choice (byte alignment). For all other systems,
1111 the @code{Default} choice is the same as @code{Component_Size} (natural
1116 If the @code{Name} parameter is present, @var{type_local_NAME} must
1117 refer to a local record or array type, and the specified alignment
1118 choice applies to the specified type. The use of
1119 @code{Component_Alignment} together with a pragma @code{Pack} causes the
1120 @code{Component_Alignment} pragma to be ignored. The use of
1121 @code{Component_Alignment} together with a record representation clause
1122 is only effective for fields not specified by the representation clause.
1124 If the @code{Name} parameter is absent, the pragma can be used as either
1125 a configuration pragma, in which case it applies to one or more units in
1126 accordance with the normal rules for configuration pragmas, or it can be
1127 used within a declarative part, in which case it applies to types that
1128 are declared within this declarative part, or within any nested scope
1129 within this declarative part. In either case it specifies the alignment
1130 to be applied to any record or array type which has otherwise standard
1133 If the alignment for a record or array type is not specified (using
1134 pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep
1135 clause), the GNAT uses the default alignment as described previously.
1137 @node Pragma Convention_Identifier
1138 @unnumberedsec Pragma Convention_Identifier
1139 @findex Convention_Identifier
1140 @cindex Conventions, synonyms
1144 @smallexample @c ada
1145 pragma Convention_Identifier (
1146 [Name =>] IDENTIFIER,
1147 [Convention =>] convention_IDENTIFIER);
1151 This pragma provides a mechanism for supplying synonyms for existing
1152 convention identifiers. The @code{Name} identifier can subsequently
1153 be used as a synonym for the given convention in other pragmas (including
1154 for example pragma @code{Import} or another @code{Convention_Identifier}
1155 pragma). As an example of the use of this, suppose you had legacy code
1156 which used Fortran77 as the identifier for Fortran. Then the pragma:
1158 @smallexample @c ada
1159 pragma Convention_Identifier (Fortran77, Fortran);
1163 would allow the use of the convention identifier @code{Fortran77} in
1164 subsequent code, avoiding the need to modify the sources. As another
1165 example, you could use this to parametrize convention requirements
1166 according to systems. Suppose you needed to use @code{Stdcall} on
1167 windows systems, and @code{C} on some other system, then you could
1168 define a convention identifier @code{Library} and use a single
1169 @code{Convention_Identifier} pragma to specify which convention
1170 would be used system-wide.
1172 @node Pragma CPP_Class
1173 @unnumberedsec Pragma CPP_Class
1175 @cindex Interfacing with C++
1179 @smallexample @c ada
1180 pragma CPP_Class ([Entity =>] local_NAME);
1184 The argument denotes an entity in the current declarative region
1185 that is declared as a tagged or untagged record type. It indicates that
1186 the type corresponds to an externally declared C++ class type, and is to
1187 be laid out the same way that C++ would lay out the type.
1189 If (and only if) the type is tagged, at least one component in the
1190 record must be of type @code{Interfaces.CPP.Vtable_Ptr}, corresponding
1191 to the C++ Vtable (or Vtables in the case of multiple inheritance) used
1194 Types for which @code{CPP_Class} is specified do not have assignment or
1195 equality operators defined (such operations can be imported or declared
1196 as subprograms as required). Initialization is allowed only by
1197 constructor functions (see pragma @code{CPP_Constructor}).
1199 Pragma @code{CPP_Class} is intended primarily for automatic generation
1200 using an automatic binding generator tool.
1201 See @ref{Interfacing to C++} for related information.
1203 @node Pragma CPP_Constructor
1204 @unnumberedsec Pragma CPP_Constructor
1205 @cindex Interfacing with C++
1206 @findex CPP_Constructor
1210 @smallexample @c ada
1211 pragma CPP_Constructor ([Entity =>] local_NAME);
1215 This pragma identifies an imported function (imported in the usual way
1216 with pragma @code{Import}) as corresponding to a C++
1217 constructor. The argument is a name that must have been
1218 previously mentioned in a pragma @code{Import}
1219 with @code{Convention} = @code{CPP}, and must be of one of the following
1224 @code{function @var{Fname} return @var{T}'Class}
1227 @code{function @var{Fname} (@dots{}) return @var{T}'Class}
1231 where @var{T} is a tagged type to which the pragma @code{CPP_Class} applies.
1233 The first form is the default constructor, used when an object of type
1234 @var{T} is created on the Ada side with no explicit constructor. Other
1235 constructors (including the copy constructor, which is simply a special
1236 case of the second form in which the one and only argument is of type
1237 @var{T}), can only appear in two contexts:
1241 On the right side of an initialization of an object of type @var{T}.
1243 In an extension aggregate for an object of a type derived from @var{T}.
1247 Although the constructor is described as a function that returns a value
1248 on the Ada side, it is typically a procedure with an extra implicit
1249 argument (the object being initialized) at the implementation
1250 level. GNAT issues the appropriate call, whatever it is, to get the
1251 object properly initialized.
1253 In the case of derived objects, you may use one of two possible forms
1254 for declaring and creating an object:
1257 @item @code{New_Object : Derived_T}
1258 @item @code{New_Object : Derived_T := (@var{constructor-call with} @dots{})}
1262 In the first case the default constructor is called and extension fields
1263 if any are initialized according to the default initialization
1264 expressions in the Ada declaration. In the second case, the given
1265 constructor is called and the extension aggregate indicates the explicit
1266 values of the extension fields.
1268 If no constructors are imported, it is impossible to create any objects
1269 on the Ada side. If no default constructor is imported, only the
1270 initialization forms using an explicit call to a constructor are
1273 Pragma @code{CPP_Constructor} is intended primarily for automatic generation
1274 using an automatic binding generator tool.
1275 See @ref{Interfacing to C++} for more related information.
1277 @node Pragma CPP_Virtual
1278 @unnumberedsec Pragma CPP_Virtual
1279 @cindex Interfacing to C++
1284 @smallexample @c ada
1287 [, [Vtable_Ptr =>] vtable_ENTITY,]
1288 [, [Position =>] static_integer_EXPRESSION]);
1292 This pragma serves the same function as pragma @code{Import} in that
1293 case of a virtual function imported from C++. The @var{Entity} argument
1295 primitive subprogram of a tagged type to which pragma @code{CPP_Class}
1296 applies. The @var{Vtable_Ptr} argument specifies
1297 the Vtable_Ptr component which contains the
1298 entry for this virtual function. The @var{Position} argument
1299 is the sequential number
1300 counting virtual functions for this Vtable starting at 1.
1302 The @code{Vtable_Ptr} and @code{Position} arguments may be omitted if
1303 there is one Vtable_Ptr present (single inheritance case) and all
1304 virtual functions are imported. In that case the compiler can deduce both
1307 No @code{External_Name} or @code{Link_Name} arguments are required for a
1308 virtual function, since it is always accessed indirectly via the
1309 appropriate Vtable entry.
1311 Pragma @code{CPP_Virtual} is intended primarily for automatic generation
1312 using an automatic binding generator tool.
1313 See @ref{Interfacing to C++} for related information.
1315 @node Pragma CPP_Vtable
1316 @unnumberedsec Pragma CPP_Vtable
1317 @cindex Interfacing with C++
1322 @smallexample @c ada
1325 [Vtable_Ptr =>] vtable_ENTITY,
1326 [Entry_Count =>] static_integer_EXPRESSION);
1330 Given a record to which the pragma @code{CPP_Class} applies,
1331 this pragma can be specified for each component of type
1332 @code{CPP.Interfaces.Vtable_Ptr}.
1333 @var{Entity} is the tagged type, @var{Vtable_Ptr}
1334 is the record field of type @code{Vtable_Ptr}, and @var{Entry_Count} is
1335 the number of virtual functions on the C++ side. Not all of these
1336 functions need to be imported on the Ada side.
1338 You may omit the @code{CPP_Vtable} pragma if there is only one
1339 @code{Vtable_Ptr} component in the record and all virtual functions are
1340 imported on the Ada side (the default value for the entry count in this
1341 case is simply the total number of virtual functions).
1343 Pragma @code{CPP_Vtable} is intended primarily for automatic generation
1344 using an automatic binding generator tool.
1345 See @ref{Interfacing to C++} for related information.
1348 @unnumberedsec Pragma Debug
1353 @smallexample @c ada
1354 pragma Debug (PROCEDURE_CALL_WITHOUT_SEMICOLON);
1356 PROCEDURE_CALL_WITHOUT_SEMICOLON ::=
1358 | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART
1362 The argument has the syntactic form of an expression, meeting the
1363 syntactic requirements for pragmas.
1365 If assertions are not enabled on the command line, this pragma has no
1366 effect. If asserts are enabled, the semantics of the pragma is exactly
1367 equivalent to the procedure call statement corresponding to the argument
1368 with a terminating semicolon. Pragmas are permitted in sequences of
1369 declarations, so you can use pragma @code{Debug} to intersperse calls to
1370 debug procedures in the middle of declarations.
1372 @node Pragma Detect_Blocking
1373 @unnumberedsec Pragma Detect_Blocking
1374 @findex Detect_Blocking
1378 @smallexample @c ada
1379 pragma Detect_Blocking;
1383 This is a configuration pragma that forces the detection of potentially
1384 blocking operations within a protected operation, and to raise Program_Error
1387 @node Pragma Elaboration_Checks
1388 @unnumberedsec Pragma Elaboration_Checks
1389 @cindex Elaboration control
1390 @findex Elaboration_Checks
1394 @smallexample @c ada
1395 pragma Elaboration_Checks (Dynamic | Static);
1399 This is a configuration pragma that provides control over the
1400 elaboration model used by the compilation affected by the
1401 pragma. If the parameter is @code{Dynamic},
1402 then the dynamic elaboration
1403 model described in the Ada Reference Manual is used, as though
1404 the @code{-gnatE} switch had been specified on the command
1405 line. If the parameter is @code{Static}, then the default GNAT static
1406 model is used. This configuration pragma overrides the setting
1407 of the command line. For full details on the elaboration models
1408 used by the GNAT compiler, see section ``Elaboration Order
1409 Handling in GNAT'' in the @cite{GNAT User's Guide}.
1411 @node Pragma Eliminate
1412 @unnumberedsec Pragma Eliminate
1413 @cindex Elimination of unused subprograms
1418 @smallexample @c ada
1420 [Unit_Name =>] IDENTIFIER |
1421 SELECTED_COMPONENT);
1424 [Unit_Name =>] IDENTIFIER |
1426 [Entity =>] IDENTIFIER |
1427 SELECTED_COMPONENT |
1429 [,OVERLOADING_RESOLUTION]);
1431 OVERLOADING_RESOLUTION ::= PARAMETER_AND_RESULT_TYPE_PROFILE |
1434 PARAMETER_AND_RESULT_TYPE_PROFILE ::= PROCEDURE_PROFILE |
1437 PROCEDURE_PROFILE ::= Parameter_Types => PARAMETER_TYPES
1439 FUNCTION_PROFILE ::= [Parameter_Types => PARAMETER_TYPES,]
1440 Result_Type => result_SUBTYPE_NAME]
1442 PARAMETER_TYPES ::= (SUBTYPE_NAME @{, SUBTYPE_NAME@})
1443 SUBTYPE_NAME ::= STRING_VALUE
1445 SOURCE_LOCATION ::= Source_Location => SOURCE_TRACE
1446 SOURCE_TRACE ::= STRING_VALUE
1448 STRING_VALUE ::= STRING_LITERAL @{& STRING_LITERAL@}
1452 This pragma indicates that the given entity is not used outside the
1453 compilation unit it is defined in. The entity must be an explicitly declared
1454 subprogram; this includes generic subprogram instances and
1455 subprograms declared in generic package instances.
1457 If the entity to be eliminated is a library level subprogram, then
1458 the first form of pragma @code{Eliminate} is used with only a single argument.
1459 In this form, the @code{Unit_Name} argument specifies the name of the
1460 library level unit to be eliminated.
1462 In all other cases, both @code{Unit_Name} and @code{Entity} arguments
1463 are required. If item is an entity of a library package, then the first
1464 argument specifies the unit name, and the second argument specifies
1465 the particular entity. If the second argument is in string form, it must
1466 correspond to the internal manner in which GNAT stores entity names (see
1467 compilation unit Namet in the compiler sources for details).
1469 The remaining parameters (OVERLOADING_RESOLUTION) are optionally used
1470 to distinguish between overloaded subprograms. If a pragma does not contain
1471 the OVERLOADING_RESOLUTION parameter(s), it is applied to all the overloaded
1472 subprograms denoted by the first two parameters.
1474 Use PARAMETER_AND_RESULT_TYPE_PROFILE to specify the profile of the subprogram
1475 to be eliminated in a manner similar to that used for the extended
1476 @code{Import} and @code{Export} pragmas, except that the subtype names are
1477 always given as strings. At the moment, this form of distinguishing
1478 overloaded subprograms is implemented only partially, so we do not recommend
1479 using it for practical subprogram elimination.
1481 Note, that in case of a parameterless procedure its profile is represented
1482 as @code{Parameter_Types => ("")}
1484 Alternatively, the @code{Source_Location} parameter is used to specify
1485 which overloaded alternative is to be eliminated by pointing to the
1486 location of the DEFINING_PROGRAM_UNIT_NAME of this subprogram in the
1487 source text. The string literal (or concatenation of string literals)
1488 given as SOURCE_TRACE must have the following format:
1490 @smallexample @c ada
1491 SOURCE_TRACE ::= SOURCE_LOCATION@{LBRACKET SOURCE_LOCATION RBRACKET@}
1496 SOURCE_LOCATION ::= FILE_NAME:LINE_NUMBER
1497 FILE_NAME ::= STRING_LITERAL
1498 LINE_NUMBER ::= DIGIT @{DIGIT@}
1501 SOURCE_TRACE should be the short name of the source file (with no directory
1502 information), and LINE_NUMBER is supposed to point to the line where the
1503 defining name of the subprogram is located.
1505 For the subprograms that are not a part of generic instantiations, only one
1506 SOURCE_LOCATION is used. If a subprogram is declared in a package
1507 instantiation, SOURCE_TRACE contains two SOURCE_LOCATIONs, the first one is
1508 the location of the (DEFINING_PROGRAM_UNIT_NAME of the) instantiation, and the
1509 second one denotes the declaration of the corresponding subprogram in the
1510 generic package. This approach is recursively used to create SOURCE_LOCATIONs
1511 in case of nested instantiations.
1513 The effect of the pragma is to allow the compiler to eliminate
1514 the code or data associated with the named entity. Any reference to
1515 an eliminated entity outside the compilation unit it is defined in,
1516 causes a compile time or link time error.
1518 The intention of pragma @code{Eliminate} is to allow a program to be compiled
1519 in a system independent manner, with unused entities eliminated, without
1520 the requirement of modifying the source text. Normally the required set
1521 of @code{Eliminate} pragmas is constructed automatically using the gnatelim
1522 tool. Elimination of unused entities local to a compilation unit is
1523 automatic, without requiring the use of pragma @code{Eliminate}.
1525 Note that the reason this pragma takes string literals where names might
1526 be expected is that a pragma @code{Eliminate} can appear in a context where the
1527 relevant names are not visible.
1529 Note that any change in the source files that includes removing, splitting of
1530 adding lines may make the set of Eliminate pragmas using SOURCE_LOCATION
1533 @node Pragma Export_Exception
1534 @unnumberedsec Pragma Export_Exception
1536 @findex Export_Exception
1540 @smallexample @c ada
1541 pragma Export_Exception (
1542 [Internal =>] local_NAME,
1543 [, [External =>] EXTERNAL_SYMBOL,]
1544 [, [Form =>] Ada | VMS]
1545 [, [Code =>] static_integer_EXPRESSION]);
1549 | static_string_EXPRESSION
1553 This pragma is implemented only in the OpenVMS implementation of GNAT@. It
1554 causes the specified exception to be propagated outside of the Ada program,
1555 so that it can be handled by programs written in other OpenVMS languages.
1556 This pragma establishes an external name for an Ada exception and makes the
1557 name available to the OpenVMS Linker as a global symbol. For further details
1558 on this pragma, see the
1559 DEC Ada Language Reference Manual, section 13.9a3.2.
1561 @node Pragma Export_Function
1562 @unnumberedsec Pragma Export_Function
1563 @cindex Argument passing mechanisms
1564 @findex Export_Function
1569 @smallexample @c ada
1570 pragma Export_Function (
1571 [Internal =>] local_NAME,
1572 [, [External =>] EXTERNAL_SYMBOL]
1573 [, [Parameter_Types =>] PARAMETER_TYPES]
1574 [, [Result_Type =>] result_SUBTYPE_MARK]
1575 [, [Mechanism =>] MECHANISM]
1576 [, [Result_Mechanism =>] MECHANISM_NAME]);
1580 | static_string_EXPRESSION
1585 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
1589 | subtype_Name ' Access
1593 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1595 MECHANISM_ASSOCIATION ::=
1596 [formal_parameter_NAME =>] MECHANISM_NAME
1604 Use this pragma to make a function externally callable and optionally
1605 provide information on mechanisms to be used for passing parameter and
1606 result values. We recommend, for the purposes of improving portability,
1607 this pragma always be used in conjunction with a separate pragma
1608 @code{Export}, which must precede the pragma @code{Export_Function}.
1609 GNAT does not require a separate pragma @code{Export}, but if none is
1610 present, @code{Convention Ada} is assumed, which is usually
1611 not what is wanted, so it is usually appropriate to use this
1612 pragma in conjunction with a @code{Export} or @code{Convention}
1613 pragma that specifies the desired foreign convention.
1614 Pragma @code{Export_Function}
1615 (and @code{Export}, if present) must appear in the same declarative
1616 region as the function to which they apply.
1618 @var{internal_name} must uniquely designate the function to which the
1619 pragma applies. If more than one function name exists of this name in
1620 the declarative part you must use the @code{Parameter_Types} and
1621 @code{Result_Type} parameters is mandatory to achieve the required
1622 unique designation. @var{subtype_ mark}s in these parameters must
1623 exactly match the subtypes in the corresponding function specification,
1624 using positional notation to match parameters with subtype marks.
1625 The form with an @code{'Access} attribute can be used to match an
1626 anonymous access parameter.
1629 @cindex Passing by descriptor
1630 Note that passing by descriptor is not supported, even on the OpenVMS
1633 @cindex Suppressing external name
1634 Special treatment is given if the EXTERNAL is an explicit null
1635 string or a static string expressions that evaluates to the null
1636 string. In this case, no external name is generated. This form
1637 still allows the specification of parameter mechanisms.
1639 @node Pragma Export_Object
1640 @unnumberedsec Pragma Export_Object
1641 @findex Export_Object
1645 @smallexample @c ada
1646 pragma Export_Object
1647 [Internal =>] local_NAME,
1648 [, [External =>] EXTERNAL_SYMBOL]
1649 [, [Size =>] EXTERNAL_SYMBOL]
1653 | static_string_EXPRESSION
1657 This pragma designates an object as exported, and apart from the
1658 extended rules for external symbols, is identical in effect to the use of
1659 the normal @code{Export} pragma applied to an object. You may use a
1660 separate Export pragma (and you probably should from the point of view
1661 of portability), but it is not required. @var{Size} is syntax checked,
1662 but otherwise ignored by GNAT@.
1664 @node Pragma Export_Procedure
1665 @unnumberedsec Pragma Export_Procedure
1666 @findex Export_Procedure
1670 @smallexample @c ada
1671 pragma Export_Procedure (
1672 [Internal =>] local_NAME
1673 [, [External =>] EXTERNAL_SYMBOL]
1674 [, [Parameter_Types =>] PARAMETER_TYPES]
1675 [, [Mechanism =>] MECHANISM]);
1679 | static_string_EXPRESSION
1684 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
1688 | subtype_Name ' Access
1692 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1694 MECHANISM_ASSOCIATION ::=
1695 [formal_parameter_NAME =>] MECHANISM_NAME
1703 This pragma is identical to @code{Export_Function} except that it
1704 applies to a procedure rather than a function and the parameters
1705 @code{Result_Type} and @code{Result_Mechanism} are not permitted.
1706 GNAT does not require a separate pragma @code{Export}, but if none is
1707 present, @code{Convention Ada} is assumed, which is usually
1708 not what is wanted, so it is usually appropriate to use this
1709 pragma in conjunction with a @code{Export} or @code{Convention}
1710 pragma that specifies the desired foreign convention.
1713 @cindex Passing by descriptor
1714 Note that passing by descriptor is not supported, even on the OpenVMS
1717 @cindex Suppressing external name
1718 Special treatment is given if the EXTERNAL is an explicit null
1719 string or a static string expressions that evaluates to the null
1720 string. In this case, no external name is generated. This form
1721 still allows the specification of parameter mechanisms.
1723 @node Pragma Export_Value
1724 @unnumberedsec Pragma Export_Value
1725 @findex Export_Value
1729 @smallexample @c ada
1730 pragma Export_Value (
1731 [Value =>] static_integer_EXPRESSION,
1732 [Link_Name =>] static_string_EXPRESSION);
1736 This pragma serves to export a static integer value for external use.
1737 The first argument specifies the value to be exported. The Link_Name
1738 argument specifies the symbolic name to be associated with the integer
1739 value. This pragma is useful for defining a named static value in Ada
1740 that can be referenced in assembly language units to be linked with
1741 the application. This pragma is currently supported only for the
1742 AAMP target and is ignored for other targets.
1744 @node Pragma Export_Valued_Procedure
1745 @unnumberedsec Pragma Export_Valued_Procedure
1746 @findex Export_Valued_Procedure
1750 @smallexample @c ada
1751 pragma Export_Valued_Procedure (
1752 [Internal =>] local_NAME
1753 [, [External =>] EXTERNAL_SYMBOL]
1754 [, [Parameter_Types =>] PARAMETER_TYPES]
1755 [, [Mechanism =>] MECHANISM]);
1759 | static_string_EXPRESSION
1764 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
1768 | subtype_Name ' Access
1772 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1774 MECHANISM_ASSOCIATION ::=
1775 [formal_parameter_NAME =>] MECHANISM_NAME
1783 This pragma is identical to @code{Export_Procedure} except that the
1784 first parameter of @var{local_NAME}, which must be present, must be of
1785 mode @code{OUT}, and externally the subprogram is treated as a function
1786 with this parameter as the result of the function. GNAT provides for
1787 this capability to allow the use of @code{OUT} and @code{IN OUT}
1788 parameters in interfacing to external functions (which are not permitted
1790 GNAT does not require a separate pragma @code{Export}, but if none is
1791 present, @code{Convention Ada} is assumed, which is almost certainly
1792 not what is wanted since the whole point of this pragma is to interface
1793 with foreign language functions, so it is usually appropriate to use this
1794 pragma in conjunction with a @code{Export} or @code{Convention}
1795 pragma that specifies the desired foreign convention.
1798 @cindex Passing by descriptor
1799 Note that passing by descriptor is not supported, even on the OpenVMS
1802 @cindex Suppressing external name
1803 Special treatment is given if the EXTERNAL is an explicit null
1804 string or a static string expressions that evaluates to the null
1805 string. In this case, no external name is generated. This form
1806 still allows the specification of parameter mechanisms.
1808 @node Pragma Extend_System
1809 @unnumberedsec Pragma Extend_System
1810 @cindex @code{system}, extending
1812 @findex Extend_System
1816 @smallexample @c ada
1817 pragma Extend_System ([Name =>] IDENTIFIER);
1821 This pragma is used to provide backwards compatibility with other
1822 implementations that extend the facilities of package @code{System}. In
1823 GNAT, @code{System} contains only the definitions that are present in
1824 the Ada 95 RM@. However, other implementations, notably the DEC Ada 83
1825 implementation, provide many extensions to package @code{System}.
1827 For each such implementation accommodated by this pragma, GNAT provides a
1828 package @code{Aux_@var{xxx}}, e.g.@: @code{Aux_DEC} for the DEC Ada 83
1829 implementation, which provides the required additional definitions. You
1830 can use this package in two ways. You can @code{with} it in the normal
1831 way and access entities either by selection or using a @code{use}
1832 clause. In this case no special processing is required.
1834 However, if existing code contains references such as
1835 @code{System.@var{xxx}} where @var{xxx} is an entity in the extended
1836 definitions provided in package @code{System}, you may use this pragma
1837 to extend visibility in @code{System} in a non-standard way that
1838 provides greater compatibility with the existing code. Pragma
1839 @code{Extend_System} is a configuration pragma whose single argument is
1840 the name of the package containing the extended definition
1841 (e.g.@: @code{Aux_DEC} for the DEC Ada case). A unit compiled under
1842 control of this pragma will be processed using special visibility
1843 processing that looks in package @code{System.Aux_@var{xxx}} where
1844 @code{Aux_@var{xxx}} is the pragma argument for any entity referenced in
1845 package @code{System}, but not found in package @code{System}.
1847 You can use this pragma either to access a predefined @code{System}
1848 extension supplied with the compiler, for example @code{Aux_DEC} or
1849 you can construct your own extension unit following the above
1850 definition. Note that such a package is a child of @code{System}
1851 and thus is considered part of the implementation. To compile
1852 it you will have to use the appropriate switch for compiling
1853 system units. See the GNAT User's Guide for details.
1855 @node Pragma External
1856 @unnumberedsec Pragma External
1861 @smallexample @c ada
1863 [ Convention =>] convention_IDENTIFIER,
1864 [ Entity =>] local_NAME
1865 [, [External_Name =>] static_string_EXPRESSION ]
1866 [, [Link_Name =>] static_string_EXPRESSION ]);
1870 This pragma is identical in syntax and semantics to pragma
1871 @code{Export} as defined in the Ada Reference Manual. It is
1872 provided for compatibility with some Ada 83 compilers that
1873 used this pragma for exactly the same purposes as pragma
1874 @code{Export} before the latter was standardized.
1876 @node Pragma External_Name_Casing
1877 @unnumberedsec Pragma External_Name_Casing
1878 @cindex Dec Ada 83 casing compatibility
1879 @cindex External Names, casing
1880 @cindex Casing of External names
1881 @findex External_Name_Casing
1885 @smallexample @c ada
1886 pragma External_Name_Casing (
1887 Uppercase | Lowercase
1888 [, Uppercase | Lowercase | As_Is]);
1892 This pragma provides control over the casing of external names associated
1893 with Import and Export pragmas. There are two cases to consider:
1896 @item Implicit external names
1897 Implicit external names are derived from identifiers. The most common case
1898 arises when a standard Ada 95 Import or Export pragma is used with only two
1901 @smallexample @c ada
1902 pragma Import (C, C_Routine);
1906 Since Ada is a case insensitive language, the spelling of the identifier in
1907 the Ada source program does not provide any information on the desired
1908 casing of the external name, and so a convention is needed. In GNAT the
1909 default treatment is that such names are converted to all lower case
1910 letters. This corresponds to the normal C style in many environments.
1911 The first argument of pragma @code{External_Name_Casing} can be used to
1912 control this treatment. If @code{Uppercase} is specified, then the name
1913 will be forced to all uppercase letters. If @code{Lowercase} is specified,
1914 then the normal default of all lower case letters will be used.
1916 This same implicit treatment is also used in the case of extended DEC Ada 83
1917 compatible Import and Export pragmas where an external name is explicitly
1918 specified using an identifier rather than a string.
1920 @item Explicit external names
1921 Explicit external names are given as string literals. The most common case
1922 arises when a standard Ada 95 Import or Export pragma is used with three
1925 @smallexample @c ada
1926 pragma Import (C, C_Routine, "C_routine");
1930 In this case, the string literal normally provides the exact casing required
1931 for the external name. The second argument of pragma
1932 @code{External_Name_Casing} may be used to modify this behavior.
1933 If @code{Uppercase} is specified, then the name
1934 will be forced to all uppercase letters. If @code{Lowercase} is specified,
1935 then the name will be forced to all lowercase letters. A specification of
1936 @code{As_Is} provides the normal default behavior in which the casing is
1937 taken from the string provided.
1941 This pragma may appear anywhere that a pragma is valid. In particular, it
1942 can be used as a configuration pragma in the @file{gnat.adc} file, in which
1943 case it applies to all subsequent compilations, or it can be used as a program
1944 unit pragma, in which case it only applies to the current unit, or it can
1945 be used more locally to control individual Import/Export pragmas.
1947 It is primarily intended for use with OpenVMS systems, where many
1948 compilers convert all symbols to upper case by default. For interfacing to
1949 such compilers (e.g.@: the DEC C compiler), it may be convenient to use
1952 @smallexample @c ada
1953 pragma External_Name_Casing (Uppercase, Uppercase);
1957 to enforce the upper casing of all external symbols.
1959 @node Pragma Finalize_Storage_Only
1960 @unnumberedsec Pragma Finalize_Storage_Only
1961 @findex Finalize_Storage_Only
1965 @smallexample @c ada
1966 pragma Finalize_Storage_Only (first_subtype_local_NAME);
1970 This pragma allows the compiler not to emit a Finalize call for objects
1971 defined at the library level. This is mostly useful for types where
1972 finalization is only used to deal with storage reclamation since in most
1973 environments it is not necessary to reclaim memory just before terminating
1974 execution, hence the name.
1976 @node Pragma Float_Representation
1977 @unnumberedsec Pragma Float_Representation
1979 @findex Float_Representation
1983 @smallexample @c ada
1984 pragma Float_Representation (FLOAT_REP);
1986 FLOAT_REP ::= VAX_Float | IEEE_Float
1991 allows control over the internal representation chosen for the predefined
1992 floating point types declared in the packages @code{Standard} and
1993 @code{System}. On all systems other than OpenVMS, the argument must
1994 be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the
1995 argument may be @code{VAX_Float} to specify the use of the VAX float
1996 format for the floating-point types in Standard. This requires that
1997 the standard runtime libraries be recompiled. See the
1998 description of the @code{GNAT LIBRARY} command in the OpenVMS version
1999 of the GNAT Users Guide for details on the use of this command.
2002 @unnumberedsec Pragma Ident
2007 @smallexample @c ada
2008 pragma Ident (static_string_EXPRESSION);
2012 This pragma provides a string identification in the generated object file,
2013 if the system supports the concept of this kind of identification string.
2014 This pragma is allowed only in the outermost declarative part or
2015 declarative items of a compilation unit. If more than one @code{Ident}
2016 pragma is given, only the last one processed is effective.
2018 On OpenVMS systems, the effect of the pragma is identical to the effect of
2019 the DEC Ada 83 pragma of the same name. Note that in DEC Ada 83, the
2020 maximum allowed length is 31 characters, so if it is important to
2021 maintain compatibility with this compiler, you should obey this length
2024 @node Pragma Import_Exception
2025 @unnumberedsec Pragma Import_Exception
2027 @findex Import_Exception
2031 @smallexample @c ada
2032 pragma Import_Exception (
2033 [Internal =>] local_NAME,
2034 [, [External =>] EXTERNAL_SYMBOL,]
2035 [, [Form =>] Ada | VMS]
2036 [, [Code =>] static_integer_EXPRESSION]);
2040 | static_string_EXPRESSION
2044 This pragma is implemented only in the OpenVMS implementation of GNAT@.
2045 It allows OpenVMS conditions (for example, from OpenVMS system services or
2046 other OpenVMS languages) to be propagated to Ada programs as Ada exceptions.
2047 The pragma specifies that the exception associated with an exception
2048 declaration in an Ada program be defined externally (in non-Ada code).
2049 For further details on this pragma, see the
2050 DEC Ada Language Reference Manual, section 13.9a.3.1.
2052 @node Pragma Import_Function
2053 @unnumberedsec Pragma Import_Function
2054 @findex Import_Function
2058 @smallexample @c ada
2059 pragma Import_Function (
2060 [Internal =>] local_NAME,
2061 [, [External =>] EXTERNAL_SYMBOL]
2062 [, [Parameter_Types =>] PARAMETER_TYPES]
2063 [, [Result_Type =>] SUBTYPE_MARK]
2064 [, [Mechanism =>] MECHANISM]
2065 [, [Result_Mechanism =>] MECHANISM_NAME]
2066 [, [First_Optional_Parameter =>] IDENTIFIER]);
2070 | static_string_EXPRESSION
2074 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
2078 | subtype_Name ' Access
2082 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
2084 MECHANISM_ASSOCIATION ::=
2085 [formal_parameter_NAME =>] MECHANISM_NAME
2090 | Descriptor [([Class =>] CLASS_NAME)]
2092 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
2096 This pragma is used in conjunction with a pragma @code{Import} to
2097 specify additional information for an imported function. The pragma
2098 @code{Import} (or equivalent pragma @code{Interface}) must precede the
2099 @code{Import_Function} pragma and both must appear in the same
2100 declarative part as the function specification.
2102 The @var{Internal} argument must uniquely designate
2103 the function to which the
2104 pragma applies. If more than one function name exists of this name in
2105 the declarative part you must use the @code{Parameter_Types} and
2106 @var{Result_Type} parameters to achieve the required unique
2107 designation. Subtype marks in these parameters must exactly match the
2108 subtypes in the corresponding function specification, using positional
2109 notation to match parameters with subtype marks.
2110 The form with an @code{'Access} attribute can be used to match an
2111 anonymous access parameter.
2113 You may optionally use the @var{Mechanism} and @var{Result_Mechanism}
2114 parameters to specify passing mechanisms for the
2115 parameters and result. If you specify a single mechanism name, it
2116 applies to all parameters. Otherwise you may specify a mechanism on a
2117 parameter by parameter basis using either positional or named
2118 notation. If the mechanism is not specified, the default mechanism
2122 @cindex Passing by descriptor
2123 Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
2125 @code{First_Optional_Parameter} applies only to OpenVMS ports of GNAT@.
2126 It specifies that the designated parameter and all following parameters
2127 are optional, meaning that they are not passed at the generated code
2128 level (this is distinct from the notion of optional parameters in Ada
2129 where the parameters are passed anyway with the designated optional
2130 parameters). All optional parameters must be of mode @code{IN} and have
2131 default parameter values that are either known at compile time
2132 expressions, or uses of the @code{'Null_Parameter} attribute.
2134 @node Pragma Import_Object
2135 @unnumberedsec Pragma Import_Object
2136 @findex Import_Object
2140 @smallexample @c ada
2141 pragma Import_Object
2142 [Internal =>] local_NAME,
2143 [, [External =>] EXTERNAL_SYMBOL],
2144 [, [Size =>] EXTERNAL_SYMBOL]);
2148 | static_string_EXPRESSION
2152 This pragma designates an object as imported, and apart from the
2153 extended rules for external symbols, is identical in effect to the use of
2154 the normal @code{Import} pragma applied to an object. Unlike the
2155 subprogram case, you need not use a separate @code{Import} pragma,
2156 although you may do so (and probably should do so from a portability
2157 point of view). @var{size} is syntax checked, but otherwise ignored by
2160 @node Pragma Import_Procedure
2161 @unnumberedsec Pragma Import_Procedure
2162 @findex Import_Procedure
2166 @smallexample @c ada
2167 pragma Import_Procedure (
2168 [Internal =>] local_NAME,
2169 [, [External =>] EXTERNAL_SYMBOL]
2170 [, [Parameter_Types =>] PARAMETER_TYPES]
2171 [, [Mechanism =>] MECHANISM]
2172 [, [First_Optional_Parameter =>] IDENTIFIER]);
2176 | static_string_EXPRESSION
2180 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
2184 | subtype_Name ' Access
2188 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
2190 MECHANISM_ASSOCIATION ::=
2191 [formal_parameter_NAME =>] MECHANISM_NAME
2196 | Descriptor [([Class =>] CLASS_NAME)]
2198 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
2202 This pragma is identical to @code{Import_Function} except that it
2203 applies to a procedure rather than a function and the parameters
2204 @code{Result_Type} and @code{Result_Mechanism} are not permitted.
2206 @node Pragma Import_Valued_Procedure
2207 @unnumberedsec Pragma Import_Valued_Procedure
2208 @findex Import_Valued_Procedure
2212 @smallexample @c ada
2213 pragma Import_Valued_Procedure (
2214 [Internal =>] local_NAME,
2215 [, [External =>] EXTERNAL_SYMBOL]
2216 [, [Parameter_Types =>] PARAMETER_TYPES]
2217 [, [Mechanism =>] MECHANISM]
2218 [, [First_Optional_Parameter =>] IDENTIFIER]);
2222 | static_string_EXPRESSION
2226 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
2230 | subtype_Name ' Access
2234 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
2236 MECHANISM_ASSOCIATION ::=
2237 [formal_parameter_NAME =>] MECHANISM_NAME
2242 | Descriptor [([Class =>] CLASS_NAME)]
2244 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
2248 This pragma is identical to @code{Import_Procedure} except that the
2249 first parameter of @var{local_NAME}, which must be present, must be of
2250 mode @code{OUT}, and externally the subprogram is treated as a function
2251 with this parameter as the result of the function. The purpose of this
2252 capability is to allow the use of @code{OUT} and @code{IN OUT}
2253 parameters in interfacing to external functions (which are not permitted
2254 in Ada functions). You may optionally use the @code{Mechanism}
2255 parameters to specify passing mechanisms for the parameters.
2256 If you specify a single mechanism name, it applies to all parameters.
2257 Otherwise you may specify a mechanism on a parameter by parameter
2258 basis using either positional or named notation. If the mechanism is not
2259 specified, the default mechanism is used.
2261 Note that it is important to use this pragma in conjunction with a separate
2262 pragma Import that specifies the desired convention, since otherwise the
2263 default convention is Ada, which is almost certainly not what is required.
2265 @node Pragma Initialize_Scalars
2266 @unnumberedsec Pragma Initialize_Scalars
2267 @findex Initialize_Scalars
2268 @cindex debugging with Initialize_Scalars
2272 @smallexample @c ada
2273 pragma Initialize_Scalars;
2277 This pragma is similar to @code{Normalize_Scalars} conceptually but has
2278 two important differences. First, there is no requirement for the pragma
2279 to be used uniformly in all units of a partition, in particular, it is fine
2280 to use this just for some or all of the application units of a partition,
2281 without needing to recompile the run-time library.
2283 In the case where some units are compiled with the pragma, and some without,
2284 then a declaration of a variable where the type is defined in package
2285 Standard or is locally declared will always be subject to initialization,
2286 as will any declaration of a scalar variable. For composite variables,
2287 whether the variable is initialized may also depend on whether the package
2288 in which the type of the variable is declared is compiled with the pragma.
2290 The other important difference is that you can control the value used
2291 for initializing scalar objects. At bind time, you can select several
2292 options for initialization. You can
2293 initialize with invalid values (similar to Normalize_Scalars, though for
2294 Initialize_Scalars it is not always possible to determine the invalid
2295 values in complex cases like signed component fields with non-standard
2296 sizes). You can also initialize with high or
2297 low values, or with a specified bit pattern. See the users guide for binder
2298 options for specifying these cases.
2300 This means that you can compile a program, and then without having to
2301 recompile the program, you can run it with different values being used
2302 for initializing otherwise uninitialized values, to test if your program
2303 behavior depends on the choice. Of course the behavior should not change,
2304 and if it does, then most likely you have an erroneous reference to an
2305 uninitialized value.
2307 It is even possible to change the value at execution time eliminating even
2308 the need to rebind with a different switch using an environment variable.
2309 See the GNAT users guide for details.
2311 Note that pragma @code{Initialize_Scalars} is particularly useful in
2312 conjunction with the enhanced validity checking that is now provided
2313 in GNAT, which checks for invalid values under more conditions.
2314 Using this feature (see description of the @code{-gnatV} flag in the
2315 users guide) in conjunction with pragma @code{Initialize_Scalars}
2316 provides a powerful new tool to assist in the detection of problems
2317 caused by uninitialized variables.
2319 Note: the use of @code{Initialize_Scalars} has a fairly extensive
2320 effect on the generated code. This may cause your code to be
2321 substantially larger. It may also cause an increase in the amount
2322 of stack required, so it is probably a good idea to turn on stack
2323 checking (see description of stack checking in the GNAT users guide)
2324 when using this pragma.
2326 @node Pragma Inline_Always
2327 @unnumberedsec Pragma Inline_Always
2328 @findex Inline_Always
2332 @smallexample @c ada
2333 pragma Inline_Always (NAME [, NAME]);
2337 Similar to pragma @code{Inline} except that inlining is not subject to
2338 the use of option @code{-gnatn} and the inlining happens regardless of
2339 whether this option is used.
2341 @node Pragma Inline_Generic
2342 @unnumberedsec Pragma Inline_Generic
2343 @findex Inline_Generic
2347 @smallexample @c ada
2348 pragma Inline_Generic (generic_package_NAME);
2352 This is implemented for compatibility with DEC Ada 83 and is recognized,
2353 but otherwise ignored, by GNAT@. All generic instantiations are inlined
2354 by default when using GNAT@.
2356 @node Pragma Interface
2357 @unnumberedsec Pragma Interface
2362 @smallexample @c ada
2364 [Convention =>] convention_identifier,
2365 [Entity =>] local_NAME
2366 [, [External_Name =>] static_string_expression],
2367 [, [Link_Name =>] static_string_expression]);
2371 This pragma is identical in syntax and semantics to
2372 the standard Ada 95 pragma @code{Import}. It is provided for compatibility
2373 with Ada 83. The definition is upwards compatible both with pragma
2374 @code{Interface} as defined in the Ada 83 Reference Manual, and also
2375 with some extended implementations of this pragma in certain Ada 83
2378 @node Pragma Interface_Name
2379 @unnumberedsec Pragma Interface_Name
2380 @findex Interface_Name
2384 @smallexample @c ada
2385 pragma Interface_Name (
2386 [Entity =>] local_NAME
2387 [, [External_Name =>] static_string_EXPRESSION]
2388 [, [Link_Name =>] static_string_EXPRESSION]);
2392 This pragma provides an alternative way of specifying the interface name
2393 for an interfaced subprogram, and is provided for compatibility with Ada
2394 83 compilers that use the pragma for this purpose. You must provide at
2395 least one of @var{External_Name} or @var{Link_Name}.
2397 @node Pragma Interrupt_Handler
2398 @unnumberedsec Pragma Interrupt_Handler
2399 @findex Interrupt_Handler
2403 @smallexample @c ada
2404 pragma Interrupt_Handler (procedure_local_NAME);
2408 This program unit pragma is supported for parameterless protected procedures
2409 as described in Annex C of the Ada Reference Manual. On the AAMP target
2410 the pragma can also be specified for nonprotected parameterless procedures
2411 that are declared at the library level (which includes procedures
2412 declared at the top level of a library package). In the case of AAMP,
2413 when this pragma is applied to a nonprotected procedure, the instruction
2414 @code{IERET} is generated for returns from the procedure, enabling
2415 maskable interrupts, in place of the normal return instruction.
2417 @node Pragma Interrupt_State
2418 @unnumberedsec Pragma Interrupt_State
2419 @findex Interrupt_State
2423 @smallexample @c ada
2424 pragma Interrupt_State (Name => value, State => SYSTEM | RUNTIME | USER);
2428 Normally certain interrupts are reserved to the implementation. Any attempt
2429 to attach an interrupt causes Program_Error to be raised, as described in
2430 RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
2431 many systems for an @kbd{Ctrl-C} interrupt. Normally this interrupt is
2432 reserved to the implementation, so that @kbd{Ctrl-C} can be used to
2433 interrupt execution. Additionally, signals such as @code{SIGSEGV},
2434 @code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific
2435 Ada exceptions, or used to implement run-time functions such as the
2436 @code{abort} statement and stack overflow checking.
2438 Pragma @code{Interrupt_State} provides a general mechanism for overriding
2439 such uses of interrupts. It subsumes the functionality of pragma
2440 @code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not
2441 available on OS/2, Windows or VMS. On all other platforms than VxWorks,
2442 it applies to signals; on VxWorks, it applies to vectored hardware interrupts
2443 and may be used to mark interrupts required by the board support package
2446 Interrupts can be in one of three states:
2450 The interrupt is reserved (no Ada handler can be installed), and the
2451 Ada run-time may not install a handler. As a result you are guaranteed
2452 standard system default action if this interrupt is raised.
2456 The interrupt is reserved (no Ada handler can be installed). The run time
2457 is allowed to install a handler for internal control purposes, but is
2458 not required to do so.
2462 The interrupt is unreserved. The user may install a handler to provide
2467 These states are the allowed values of the @code{State} parameter of the
2468 pragma. The @code{Name} parameter is a value of the type
2469 @code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in
2470 @code{Ada.Interrupts.Names}.
2472 This is a configuration pragma, and the binder will check that there
2473 are no inconsistencies between different units in a partition in how a
2474 given interrupt is specified. It may appear anywhere a pragma is legal.
2476 The effect is to move the interrupt to the specified state.
2478 By declaring interrupts to be SYSTEM, you guarantee the standard system
2479 action, such as a core dump.
2481 By declaring interrupts to be USER, you guarantee that you can install
2484 Note that certain signals on many operating systems cannot be caught and
2485 handled by applications. In such cases, the pragma is ignored. See the
2486 operating system documentation, or the value of the array @code{Reserved}
2487 declared in the specification of package @code{System.OS_Interface}.
2489 Overriding the default state of signals used by the Ada runtime may interfere
2490 with an application's runtime behavior in the cases of the synchronous signals,
2491 and in the case of the signal used to implement the @code{abort} statement.
2493 @node Pragma Keep_Names
2494 @unnumberedsec Pragma Keep_Names
2499 @smallexample @c ada
2500 pragma Keep_Names ([On =>] enumeration_first_subtype_local_NAME);
2504 The @var{local_NAME} argument
2505 must refer to an enumeration first subtype
2506 in the current declarative part. The effect is to retain the enumeration
2507 literal names for use by @code{Image} and @code{Value} even if a global
2508 @code{Discard_Names} pragma applies. This is useful when you want to
2509 generally suppress enumeration literal names and for example you therefore
2510 use a @code{Discard_Names} pragma in the @file{gnat.adc} file, but you
2511 want to retain the names for specific enumeration types.
2513 @node Pragma License
2514 @unnumberedsec Pragma License
2516 @cindex License checking
2520 @smallexample @c ada
2521 pragma License (Unrestricted | GPL | Modified_GPL | Restricted);
2525 This pragma is provided to allow automated checking for appropriate license
2526 conditions with respect to the standard and modified GPL@. A pragma
2527 @code{License}, which is a configuration pragma that typically appears at
2528 the start of a source file or in a separate @file{gnat.adc} file, specifies
2529 the licensing conditions of a unit as follows:
2533 This is used for a unit that can be freely used with no license restrictions.
2534 Examples of such units are public domain units, and units from the Ada
2538 This is used for a unit that is licensed under the unmodified GPL, and which
2539 therefore cannot be @code{with}'ed by a restricted unit.
2542 This is used for a unit licensed under the GNAT modified GPL that includes
2543 a special exception paragraph that specifically permits the inclusion of
2544 the unit in programs without requiring the entire program to be released
2545 under the GPL@. This is the license used for the GNAT run-time which ensures
2546 that the run-time can be used freely in any program without GPL concerns.
2549 This is used for a unit that is restricted in that it is not permitted to
2550 depend on units that are licensed under the GPL@. Typical examples are
2551 proprietary code that is to be released under more restrictive license
2552 conditions. Note that restricted units are permitted to @code{with} units
2553 which are licensed under the modified GPL (this is the whole point of the
2559 Normally a unit with no @code{License} pragma is considered to have an
2560 unknown license, and no checking is done. However, standard GNAT headers
2561 are recognized, and license information is derived from them as follows.
2565 A GNAT license header starts with a line containing 78 hyphens. The following
2566 comment text is searched for the appearance of any of the following strings.
2568 If the string ``GNU General Public License'' is found, then the unit is assumed
2569 to have GPL license, unless the string ``As a special exception'' follows, in
2570 which case the license is assumed to be modified GPL@.
2572 If one of the strings
2573 ``This specification is adapted from the Ada Semantic Interface'' or
2574 ``This specification is derived from the Ada Reference Manual'' is found
2575 then the unit is assumed to be unrestricted.
2579 These default actions means that a program with a restricted license pragma
2580 will automatically get warnings if a GPL unit is inappropriately
2581 @code{with}'ed. For example, the program:
2583 @smallexample @c ada
2586 procedure Secret_Stuff is
2592 if compiled with pragma @code{License} (@code{Restricted}) in a
2593 @file{gnat.adc} file will generate the warning:
2598 >>> license of withed unit "Sem_Ch3" is incompatible
2600 2. with GNAT.Sockets;
2601 3. procedure Secret_Stuff is
2605 Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT
2606 compiler and is licensed under the
2607 GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT
2608 run time, and is therefore licensed under the modified GPL@.
2610 @node Pragma Link_With
2611 @unnumberedsec Pragma Link_With
2616 @smallexample @c ada
2617 pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@});
2621 This pragma is provided for compatibility with certain Ada 83 compilers.
2622 It has exactly the same effect as pragma @code{Linker_Options} except
2623 that spaces occurring within one of the string expressions are treated
2624 as separators. For example, in the following case:
2626 @smallexample @c ada
2627 pragma Link_With ("-labc -ldef");
2631 results in passing the strings @code{-labc} and @code{-ldef} as two
2632 separate arguments to the linker. In addition pragma Link_With allows
2633 multiple arguments, with the same effect as successive pragmas.
2635 @node Pragma Linker_Alias
2636 @unnumberedsec Pragma Linker_Alias
2637 @findex Linker_Alias
2641 @smallexample @c ada
2642 pragma Linker_Alias (
2643 [Entity =>] local_NAME
2644 [Target =>] static_string_EXPRESSION);
2648 @var{local_NAME} must refer to an object that is declared at the library
2649 level. This pragma establishes the given entity as a linker alias for the
2650 given target. It is equivalent to @code{__attribute__((alias))} in GNU C
2651 and causes @var{local_NAME} to be emitted as an alias for the symbol
2652 @var{static_string_EXPRESSION} in the object file, that is to say no space
2653 is reserved for @var{local_NAME} by the assembler and it will be resolved
2654 to the same address as @var{static_string_EXPRESSION} by the linker.
2656 The actual linker name for the target must be used (e.g. the fully
2657 encoded name with qualification in Ada, or the mangled name in C++),
2658 or it must be declared using the C convention with @code{pragma Import}
2659 or @code{pragma Export}.
2661 Not all target machines support this pragma. On some of them it is accepted
2662 only if @code{pragma Weak_External} has been applied to @var{local_NAME}.
2664 @smallexample @c ada
2665 -- Example of the use of pragma Linker_Alias
2669 pragma Export (C, i);
2671 new_name_for_i : Integer;
2672 pragma Linker_Alias (new_name_for_i, "i");
2676 @node Pragma Linker_Constructor
2677 @unnumberedsec Pragma Linker_Constructor
2678 @findex Linker_Constructor
2682 @smallexample @c ada
2683 pragma Linker_Constructor (procedure_LOCAL_NAME);
2687 @var{procedure_local_NAME} must refer to a parameterless procedure that
2688 is declared at the library level. A procedure to which this pragma is
2689 applied will be treated as an initialization routine by the linker.
2690 It is equivalent to @code{__attribute__((constructor))} in GNU C and
2691 causes @var{procedure_LOCAL_NAME} to be invoked before the entry point
2692 of the executable is called (or immediately after the shared library is
2693 loaded if the procedure is linked in a shared library), in particular
2694 before the Ada run-time environment is set up.
2696 Because of these specific contexts, the set of operations such a procedure
2697 can perform is very limited and the type of objects it can manipulate is
2698 essentially restricted to the elementary types. In particular, it must only
2699 contain code to which pragma Restrictions (No_Elaboration_Code) applies.
2701 This pragma is used by GNAT to implement auto-initialization of shared Stand
2702 Alone Libraries, which provides a related capability without the restrictions
2703 listed above. Where possible, the use of Stand Alone Libraries is preferable
2704 to the use of this pragma.
2706 @node Pragma Linker_Destructor
2707 @unnumberedsec Pragma Linker_Destructor
2708 @findex Linker_Destructor
2712 @smallexample @c ada
2713 pragma Linker_Destructor (procedure_LOCAL_NAME);
2717 @var{procedure_local_NAME} must refer to a parameterless procedure that
2718 is declared at the library level. A procedure to which this pragma is
2719 applied will be treated as a finalization routine by the linker.
2720 It is equivalent to @code{__attribute__((destructor))} in GNU C and
2721 causes @var{procedure_LOCAL_NAME} to be invoked after the entry point
2722 of the executable has exited (or immediately before the shared library
2723 is unloaded if the procedure is linked in a shared library), in particular
2724 after the Ada run-time environment is shut down.
2726 See @code{pragma Linker_Constructor} for the set of restrictions that apply
2727 because of these specific contexts.
2729 @node Pragma Linker_Section
2730 @unnumberedsec Pragma Linker_Section
2731 @findex Linker_Section
2735 @smallexample @c ada
2736 pragma Linker_Section (
2737 [Entity =>] local_NAME
2738 [Section =>] static_string_EXPRESSION);
2742 @var{local_NAME} must refer to an object that is declared at the library
2743 level. This pragma specifies the name of the linker section for the given
2744 entity. It is equivalent to @code{__attribute__((section))} in GNU C and
2745 causes @var{local_NAME} to be placed in the @var{static_string_EXPRESSION}
2746 section of the executable (assuming the linker doesn't rename the section).
2748 The compiler normally places library-level objects in standard sections
2749 depending on their type: procedures and functions generally go in the
2750 @code{.text} section, initialized variables in the @code{.data} section
2751 and uninitialized variables in the @code{.bss} section.
2753 Other, special sections may exist on given target machines to map special
2754 hardware, for example I/O ports or flash memory. This pragma is a means to
2755 defer the final layout of the executable to the linker, thus fully working
2756 at the symbolic level with the compiler.
2758 Some file formats do not support arbitrary sections so not all target
2759 machines support this pragma. The use of this pragma may cause a program
2760 execution to be erroneous if it is used to place an entity into an
2761 inappropriate section (e.g. a modified variable into the @code{.text}
2762 section). See also @code{pragma Persistent_BSS}.
2764 @smallexample @c ada
2765 -- Example of the use of pragma Linker_Section
2769 pragma Volatile (Port_A);
2770 pragma Linker_Section (Port_A, ".bss.port_a");
2773 pragma Volatile (Port_B);
2774 pragma Linker_Section (Port_B, ".bss.port_b");
2778 @node Pragma Long_Float
2779 @unnumberedsec Pragma Long_Float
2785 @smallexample @c ada
2786 pragma Long_Float (FLOAT_FORMAT);
2788 FLOAT_FORMAT ::= D_Float | G_Float
2792 This pragma is implemented only in the OpenVMS implementation of GNAT@.
2793 It allows control over the internal representation chosen for the predefined
2794 type @code{Long_Float} and for floating point type representations with
2795 @code{digits} specified in the range 7 through 15.
2796 For further details on this pragma, see the
2797 @cite{DEC Ada Language Reference Manual}, section 3.5.7b. Note that to use
2798 this pragma, the standard runtime libraries must be recompiled. See the
2799 description of the @code{GNAT LIBRARY} command in the OpenVMS version
2800 of the GNAT User's Guide for details on the use of this command.
2802 @node Pragma Machine_Attribute
2803 @unnumberedsec Pragma Machine_Attribute
2804 @findex Machine_Attribute
2808 @smallexample @c ada
2809 pragma Machine_Attribute (
2810 [Attribute_Name =>] string_EXPRESSION,
2811 [Entity =>] local_NAME);
2815 Machine-dependent attributes can be specified for types and/or
2816 declarations. This pragma is semantically equivalent to
2817 @code{__attribute__((@var{string_expression}))} in GNU C,
2818 where @code{@var{string_expression}} is
2819 recognized by the target macro @code{TARGET_ATTRIBUTE_TABLE} which is
2820 defined for each machine. See the GCC manual for further information.
2821 It is not possible to specify attributes defined by other languages,
2822 only attributes defined by the machine the code is intended to run on.
2824 @node Pragma Main_Storage
2825 @unnumberedsec Pragma Main_Storage
2827 @findex Main_Storage
2831 @smallexample @c ada
2833 (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]);
2835 MAIN_STORAGE_OPTION ::=
2836 [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION
2837 | [TOP_GUARD =>] static_SIMPLE_EXPRESSION
2842 This pragma is provided for compatibility with OpenVMS VAX Systems. It has
2843 no effect in GNAT, other than being syntax checked. Note that the pragma
2844 also has no effect in DEC Ada 83 for OpenVMS Alpha Systems.
2846 @node Pragma No_Return
2847 @unnumberedsec Pragma No_Return
2852 @smallexample @c ada
2853 pragma No_Return (procedure_local_NAME);
2857 @var{procedure_local_NAME} must refer to one or more procedure
2858 declarations in the current declarative part. A procedure to which this
2859 pragma is applied may not contain any explicit @code{return} statements,
2860 and also may not contain any implicit return statements from falling off
2861 the end of a statement sequence. One use of this pragma is to identify
2862 procedures whose only purpose is to raise an exception.
2864 Another use of this pragma is to suppress incorrect warnings about
2865 missing returns in functions, where the last statement of a function
2866 statement sequence is a call to such a procedure.
2868 @node Pragma Normalize_Scalars
2869 @unnumberedsec Pragma Normalize_Scalars
2870 @findex Normalize_Scalars
2874 @smallexample @c ada
2875 pragma Normalize_Scalars;
2879 This is a language defined pragma which is fully implemented in GNAT@. The
2880 effect is to cause all scalar objects that are not otherwise initialized
2881 to be initialized. The initial values are implementation dependent and
2885 @item Standard.Character
2887 Objects whose root type is Standard.Character are initialized to
2888 Character'Last unless the subtype range excludes NUL (in which case
2889 NUL is used). This choice will always generate an invalid value if
2892 @item Standard.Wide_Character
2894 Objects whose root type is Standard.Wide_Character are initialized to
2895 Wide_Character'Last unless the subtype range excludes NUL (in which case
2896 NUL is used). This choice will always generate an invalid value if
2899 @item Standard.Wide_Wide_Character
2901 Objects whose root type is Standard.Wide_Wide_Character are initialized to
2902 the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in
2903 which case NUL is used). This choice will always generate an invalid value if
2908 Objects of an integer type are treated differently depending on whether
2909 negative values are present in the subtype. If no negative values are
2910 present, then all one bits is used as the initial value except in the
2911 special case where zero is excluded from the subtype, in which case
2912 all zero bits are used. This choice will always generate an invalid
2913 value if one exists.
2915 For subtypes with negative values present, the largest negative number
2916 is used, except in the unusual case where this largest negative number
2917 is in the subtype, and the largest positive number is not, in which case
2918 the largest positive value is used. This choice will always generate
2919 an invalid value if one exists.
2921 @item Floating-Point Types
2922 Objects of all floating-point types are initialized to all 1-bits. For
2923 standard IEEE format, this corresponds to a NaN (not a number) which is
2924 indeed an invalid value.
2926 @item Fixed-Point Types
2927 Objects of all fixed-point types are treated as described above for integers,
2928 with the rules applying to the underlying integer value used to represent
2929 the fixed-point value.
2932 Objects of a modular type are initialized to all one bits, except in
2933 the special case where zero is excluded from the subtype, in which
2934 case all zero bits are used. This choice will always generate an
2935 invalid value if one exists.
2937 @item Enumeration types
2938 Objects of an enumeration type are initialized to all one-bits, i.e.@: to
2939 the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal
2940 whose Pos value is zero, in which case a code of zero is used. This choice
2941 will always generate an invalid value if one exists.
2945 @node Pragma Obsolescent
2946 @unnumberedsec Pragma Obsolescent
2951 @smallexample @c ada
2952 pragma Obsolescent [(static_string_EXPRESSION [,Ada_05])];
2956 This pragma must occur immediately following a subprogram
2957 declaration. It indicates that the associated function or procedure
2958 is considered obsolescent and should not be used. Typically this is
2959 used when an API must be modified by eventually removing or modifying
2960 existing subprograms. The pragma can be used at an intermediate stage
2961 when the subprogram is still present, but will be removed later.
2963 The effect of this pragma is to output a warning message that the
2964 subprogram is obsolescent if the appropriate warning option in the
2965 compiler is activated. If a parameter is present, then a second
2966 warning message is given containing this text.
2968 In addition, a call to such a program is considered a violation of
2969 pragma Restrictions (No_Obsolescent_Features).
2971 If the optional second parameter is present (which must be exactly
2972 the identifier Ada_05, no other argument is allowed), then the
2973 indication of obsolescence applies only when compiling in Ada 2005
2974 mode. This is primarily intended for dealing with the situations
2975 in the predefined library where subprograms have become defined
2976 as obsolescent in Ada 2005 (e.g. in Ada.Characters.Handling), but
2977 may be used anywhere.
2979 @node Pragma Passive
2980 @unnumberedsec Pragma Passive
2985 @smallexample @c ada
2986 pragma Passive ([Semaphore | No]);
2990 Syntax checked, but otherwise ignored by GNAT@. This is recognized for
2991 compatibility with DEC Ada 83 implementations, where it is used within a
2992 task definition to request that a task be made passive. If the argument
2993 @code{Semaphore} is present, or the argument is omitted, then DEC Ada 83
2994 treats the pragma as an assertion that the containing task is passive
2995 and that optimization of context switch with this task is permitted and
2996 desired. If the argument @code{No} is present, the task must not be
2997 optimized. GNAT does not attempt to optimize any tasks in this manner
2998 (since protected objects are available in place of passive tasks).
3000 @node Pragma Persistent_BSS
3001 @unnumberedsec Pragma Persistent_BSS
3002 @findex Persistent_BSS
3006 @smallexample @c ada
3007 pragma Persistent_BSS [local_NAME]
3011 This pragma allows selected objects to be placed in the @code{.persistent_bss}
3012 section. On some targets the linker and loader provide for special
3013 treatment of this section, allowing a program to be reloaded without
3014 affecting the contents of this data (hence the name persistent).
3016 There are two forms of usage. If an argument is given, it must be the
3017 local name of a library level object, with no explicit initialization
3018 and whose type is potentially persistent. If no argument is given, then
3019 the pragma is a configuration pragma, and applies to all library level
3020 objects with no explicit initialization of potentially persistent types.
3022 A potentially persistent type is a scalar type, or a non-tagged,
3023 non-discriminated record, all of whose components have no explicit
3024 initialization and are themselves of a potentially persistent type,
3025 or an array, all of whose constraints are static, and whose component
3026 type is potentially persistent.
3028 If this pragma is used on a target where this feature is not supported,
3029 then the pragma will be ignored. See also @code{pragma Linker_Section}.
3031 @node Pragma Polling
3032 @unnumberedsec Pragma Polling
3037 @smallexample @c ada
3038 pragma Polling (ON | OFF);
3042 This pragma controls the generation of polling code. This is normally off.
3043 If @code{pragma Polling (ON)} is used then periodic calls are generated to
3044 the routine @code{Ada.Exceptions.Poll}. This routine is a separate unit in the
3045 runtime library, and can be found in file @file{a-excpol.adb}.
3047 Pragma @code{Polling} can appear as a configuration pragma (for example it
3048 can be placed in the @file{gnat.adc} file) to enable polling globally, or it
3049 can be used in the statement or declaration sequence to control polling
3052 A call to the polling routine is generated at the start of every loop and
3053 at the start of every subprogram call. This guarantees that the @code{Poll}
3054 routine is called frequently, and places an upper bound (determined by
3055 the complexity of the code) on the period between two @code{Poll} calls.
3057 The primary purpose of the polling interface is to enable asynchronous
3058 aborts on targets that cannot otherwise support it (for example Windows
3059 NT), but it may be used for any other purpose requiring periodic polling.
3060 The standard version is null, and can be replaced by a user program. This
3061 will require re-compilation of the @code{Ada.Exceptions} package that can
3062 be found in files @file{a-except.ads} and @file{a-except.adb}.
3064 A standard alternative unit (in file @file{4wexcpol.adb} in the standard GNAT
3065 distribution) is used to enable the asynchronous abort capability on
3066 targets that do not normally support the capability. The version of
3067 @code{Poll} in this file makes a call to the appropriate runtime routine
3068 to test for an abort condition.
3070 Note that polling can also be enabled by use of the @code{-gnatP} switch. See
3071 the @cite{GNAT User's Guide} for details.
3073 @node Pragma Profile (Ravenscar)
3074 @unnumberedsec Pragma Profile (Ravenscar)
3079 @smallexample @c ada
3080 pragma Profile (Ravenscar);
3084 A configuration pragma that establishes the following set of configuration
3088 @item Task_Dispatching_Policy (FIFO_Within_Priorities)
3089 [RM D.2.2] Tasks are dispatched following a preemptive
3090 priority-ordered scheduling policy.
3092 @item Locking_Policy (Ceiling_Locking)
3093 [RM D.3] While tasks and interrupts execute a protected action, they inherit
3094 the ceiling priority of the corresponding protected object.
3096 @c @item Detect_Blocking
3097 @c This pragma forces the detection of potentially blocking operations within a
3098 @c protected operation, and to raise Program_Error if that happens.
3102 plus the following set of restrictions:
3105 @item Max_Entry_Queue_Length = 1
3106 Defines the maximum number of calls that are queued on a (protected) entry.
3107 Note that this restrictions is checked at run time. Violation of this
3108 restriction results in the raising of Program_Error exception at the point of
3109 the call. For the Profile (Ravenscar) the value of Max_Entry_Queue_Length is
3110 always 1 and hence no task can be queued on a protected entry.
3112 @item Max_Protected_Entries = 1
3113 [RM D.7] Specifies the maximum number of entries per protected type. The
3114 bounds of every entry family of a protected unit shall be static, or shall be
3115 defined by a discriminant of a subtype whose corresponding bound is static.
3116 For the Profile (Ravenscar) the value of Max_Protected_Entries is always 1.
3118 @item Max_Task_Entries = 0
3119 [RM D.7] Specifies the maximum number of entries
3120 per task. The bounds of every entry family
3121 of a task unit shall be static, or shall be
3122 defined by a discriminant of a subtype whose
3123 corresponding bound is static. A value of zero
3124 indicates that no rendezvous are possible. For
3125 the Profile (Ravenscar), the value of Max_Task_Entries is always
3128 @item No_Abort_Statements
3129 [RM D.7] There are no abort_statements, and there are
3130 no calls to Task_Identification.Abort_Task.
3132 @item No_Asynchronous_Control
3133 [RM D.7] There are no semantic dependences on the package
3134 Asynchronous_Task_Control.
3137 There are no semantic dependencies on the package Ada.Calendar.
3139 @item No_Dynamic_Attachment
3140 There is no call to any of the operations defined in package Ada.Interrupts
3141 (Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler,
3142 Detach_Handler, and Reference).
3144 @item No_Dynamic_Priorities
3145 [RM D.7] There are no semantic dependencies on the package Dynamic_Priorities.
3147 @item No_Implicit_Heap_Allocations
3148 [RM D.7] No constructs are allowed to cause implicit heap allocation.
3150 @item No_Local_Protected_Objects
3151 Protected objects and access types that designate
3152 such objects shall be declared only at library level.
3154 @item No_Protected_Type_Allocators
3155 There are no allocators for protected types or
3156 types containing protected subcomponents.
3158 @item No_Relative_Delay
3159 There are no delay_relative statements.
3161 @item No_Requeue_Statements
3162 Requeue statements are not allowed.
3164 @item No_Select_Statements
3165 There are no select_statements.
3167 @item No_Task_Allocators
3168 [RM D.7] There are no allocators for task types
3169 or types containing task subcomponents.
3171 @item No_Task_Attributes_Package
3172 There are no semantic dependencies on the Ada.Task_Attributes package.
3174 @item No_Task_Hierarchy
3175 [RM D.7] All (non-environment) tasks depend
3176 directly on the environment task of the partition.
3178 @item No_Task_Termination
3179 Tasks which terminate are erroneous.
3181 @item Simple_Barriers
3182 Entry barrier condition expressions shall be either static
3183 boolean expressions or boolean objects which are declared in
3184 the protected type which contains the entry.
3188 This set of configuration pragmas and restrictions correspond to the
3189 definition of the ``Ravenscar Profile'' for limited tasking, devised and
3190 published by the @cite{International Real-Time Ada Workshop}, 1997,
3191 and whose most recent description is available at
3192 @url{ftp://ftp.openravenscar.org/openravenscar/ravenscar00.pdf}.
3194 The original definition of the profile was revised at subsequent IRTAW
3195 meetings. It has been included in the ISO
3196 @cite{Guide for the Use of the Ada Programming Language in High
3197 Integrity Systems}, and has been approved by ISO/IEC/SC22/WG9 for inclusion in
3198 the next revision of the standard. The formal definition given by
3199 the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and
3200 AI-305) available at
3201 @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs/AI-00249.TXT} and
3202 @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs/AI-00305.TXT}
3205 The above set is a superset of the restrictions provided by pragma
3206 @code{Profile (Restricted)}, it includes six additional restrictions
3207 (@code{Simple_Barriers}, @code{No_Select_Statements},
3208 @code{No_Calendar}, @code{No_Implicit_Heap_Allocations},
3209 @code{No_Relative_Delay} and @code{No_Task_Termination}). This means
3210 that pragma @code{Profile (Ravenscar)}, like the pragma
3211 @code{Profile (Restricted)},
3212 automatically causes the use of a simplified,
3213 more efficient version of the tasking run-time system.
3215 @node Pragma Profile (Restricted)
3216 @unnumberedsec Pragma Profile (Restricted)
3217 @findex Restricted Run Time
3221 @smallexample @c ada
3222 pragma Profile (Restricted);
3226 A configuration pragma that establishes the following set of restrictions:
3229 @item No_Abort_Statements
3230 @item No_Entry_Queue
3231 @item No_Task_Hierarchy
3232 @item No_Task_Allocators
3233 @item No_Dynamic_Priorities
3234 @item No_Terminate_Alternatives
3235 @item No_Dynamic_Attachment
3236 @item No_Protected_Type_Allocators
3237 @item No_Local_Protected_Objects
3238 @item No_Requeue_Statements
3239 @item No_Task_Attributes_Package
3240 @item Max_Asynchronous_Select_Nesting = 0
3241 @item Max_Task_Entries = 0
3242 @item Max_Protected_Entries = 1
3243 @item Max_Select_Alternatives = 0
3247 This set of restrictions causes the automatic selection of a simplified
3248 version of the run time that provides improved performance for the
3249 limited set of tasking functionality permitted by this set of restrictions.
3251 @node Pragma Propagate_Exceptions
3252 @unnumberedsec Pragma Propagate_Exceptions
3253 @findex Propagate_Exceptions
3254 @cindex Zero Cost Exceptions
3258 @smallexample @c ada
3259 pragma Propagate_Exceptions (subprogram_local_NAME);
3263 This pragma indicates that the given entity, which is the name of an
3264 imported foreign-language subprogram may receive an Ada exception,
3265 and that the exception should be propagated. It is relevant only if
3266 zero cost exception handling is in use, and is thus never needed if
3267 the alternative @code{longjmp} / @code{setjmp} implementation of
3268 exceptions is used (although it is harmless to use it in such cases).
3270 The implementation of fast exceptions always properly propagates
3271 exceptions through Ada code, as described in the Ada Reference Manual.
3272 However, this manual is silent about the propagation of exceptions
3273 through foreign code. For example, consider the
3274 situation where @code{P1} calls
3275 @code{P2}, and @code{P2} calls @code{P3}, where
3276 @code{P1} and @code{P3} are in Ada, but @code{P2} is in C@.
3277 @code{P3} raises an Ada exception. The question is whether or not
3278 it will be propagated through @code{P2} and can be handled in
3281 For the @code{longjmp} / @code{setjmp} implementation of exceptions,
3282 the answer is always yes. For some targets on which zero cost exception
3283 handling is implemented, the answer is also always yes. However, there
3284 are some targets, notably in the current version all x86 architecture
3285 targets, in which the answer is that such propagation does not
3286 happen automatically. If such propagation is required on these
3287 targets, it is mandatory to use @code{Propagate_Exceptions} to
3288 name all foreign language routines through which Ada exceptions
3291 @node Pragma Psect_Object
3292 @unnumberedsec Pragma Psect_Object
3293 @findex Psect_Object
3297 @smallexample @c ada
3298 pragma Psect_Object (
3299 [Internal =>] local_NAME,
3300 [, [External =>] EXTERNAL_SYMBOL]
3301 [, [Size =>] EXTERNAL_SYMBOL]);
3305 | static_string_EXPRESSION
3309 This pragma is identical in effect to pragma @code{Common_Object}.
3311 @node Pragma Pure_Function
3312 @unnumberedsec Pragma Pure_Function
3313 @findex Pure_Function
3317 @smallexample @c ada
3318 pragma Pure_Function ([Entity =>] function_local_NAME);
3322 This pragma appears in the same declarative part as a function
3323 declaration (or a set of function declarations if more than one
3324 overloaded declaration exists, in which case the pragma applies
3325 to all entities). It specifies that the function @code{Entity} is
3326 to be considered pure for the purposes of code generation. This means
3327 that the compiler can assume that there are no side effects, and
3328 in particular that two calls with identical arguments produce the
3329 same result. It also means that the function can be used in an
3332 Note that, quite deliberately, there are no static checks to try
3333 to ensure that this promise is met, so @code{Pure_Function} can be used
3334 with functions that are conceptually pure, even if they do modify
3335 global variables. For example, a square root function that is
3336 instrumented to count the number of times it is called is still
3337 conceptually pure, and can still be optimized, even though it
3338 modifies a global variable (the count). Memo functions are another
3339 example (where a table of previous calls is kept and consulted to
3340 avoid re-computation).
3343 Note: Most functions in a @code{Pure} package are automatically pure, and
3344 there is no need to use pragma @code{Pure_Function} for such functions. One
3345 exception is any function that has at least one formal of type
3346 @code{System.Address} or a type derived from it. Such functions are not
3347 considered pure by default, since the compiler assumes that the
3348 @code{Address} parameter may be functioning as a pointer and that the
3349 referenced data may change even if the address value does not.
3350 Similarly, imported functions are not considered to be pure by default,
3351 since there is no way of checking that they are in fact pure. The use
3352 of pragma @code{Pure_Function} for such a function will override these default
3353 assumption, and cause the compiler to treat a designated subprogram as pure
3356 Note: If pragma @code{Pure_Function} is applied to a renamed function, it
3357 applies to the underlying renamed function. This can be used to
3358 disambiguate cases of overloading where some but not all functions
3359 in a set of overloaded functions are to be designated as pure.
3361 @node Pragma Restriction_Warnings
3362 @unnumberedsec Pragma Restriction_Warnings
3363 @findex Restriction_Warnings
3367 @smallexample @c ada
3368 pragma Restriction_Warnings
3369 (restriction_IDENTIFIER @{, restriction_IDENTIFIER@});
3373 This pragma allows a series of restriction identifiers to be
3374 specified (the list of allowed identifiers is the same as for
3375 pragma @code{Restrictions}). For each of these identifiers
3376 the compiler checks for violations of the restriction, but
3377 generates a warning message rather than an error message
3378 if the restriction is violated.
3380 @node Pragma Source_File_Name
3381 @unnumberedsec Pragma Source_File_Name
3382 @findex Source_File_Name
3386 @smallexample @c ada
3387 pragma Source_File_Name (
3388 [Unit_Name =>] unit_NAME,
3389 Spec_File_Name => STRING_LITERAL);
3391 pragma Source_File_Name (
3392 [Unit_Name =>] unit_NAME,
3393 Body_File_Name => STRING_LITERAL);
3397 Use this to override the normal naming convention. It is a configuration
3398 pragma, and so has the usual applicability of configuration pragmas
3399 (i.e.@: it applies to either an entire partition, or to all units in a
3400 compilation, or to a single unit, depending on how it is used.
3401 @var{unit_name} is mapped to @var{file_name_literal}. The identifier for
3402 the second argument is required, and indicates whether this is the file
3403 name for the spec or for the body.
3405 Another form of the @code{Source_File_Name} pragma allows
3406 the specification of patterns defining alternative file naming schemes
3407 to apply to all files.
3409 @smallexample @c ada
3410 pragma Source_File_Name
3411 (Spec_File_Name => STRING_LITERAL
3412 [,Casing => CASING_SPEC]
3413 [,Dot_Replacement => STRING_LITERAL]);
3415 pragma Source_File_Name
3416 (Body_File_Name => STRING_LITERAL
3417 [,Casing => CASING_SPEC]
3418 [,Dot_Replacement => STRING_LITERAL]);
3420 pragma Source_File_Name
3421 (Subunit_File_Name => STRING_LITERAL
3422 [,Casing => CASING_SPEC]
3423 [,Dot_Replacement => STRING_LITERAL]);
3425 CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
3429 The first argument is a pattern that contains a single asterisk indicating
3430 the point at which the unit name is to be inserted in the pattern string
3431 to form the file name. The second argument is optional. If present it
3432 specifies the casing of the unit name in the resulting file name string.
3433 The default is lower case. Finally the third argument allows for systematic
3434 replacement of any dots in the unit name by the specified string literal.
3436 A pragma Source_File_Name cannot appear after a
3437 @ref{Pragma Source_File_Name_Project}.
3439 For more details on the use of the @code{Source_File_Name} pragma,
3440 see the sections ``Using Other File Names'' and
3441 ``Alternative File Naming Schemes'' in the @cite{GNAT User's Guide}.
3443 @node Pragma Source_File_Name_Project
3444 @unnumberedsec Pragma Source_File_Name_Project
3445 @findex Source_File_Name_Project
3448 This pragma has the same syntax and semantics as pragma Source_File_Name.
3449 It is only allowed as a stand alone configuration pragma.
3450 It cannot appear after a @ref{Pragma Source_File_Name}, and
3451 most importantly, once pragma Source_File_Name_Project appears,
3452 no further Source_File_Name pragmas are allowed.
3454 The intention is that Source_File_Name_Project pragmas are always
3455 generated by the Project Manager in a manner consistent with the naming
3456 specified in a project file, and when naming is controlled in this manner,
3457 it is not permissible to attempt to modify this naming scheme using
3458 Source_File_Name pragmas (which would not be known to the project manager).
3460 @node Pragma Source_Reference
3461 @unnumberedsec Pragma Source_Reference
3462 @findex Source_Reference
3466 @smallexample @c ada
3467 pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL);
3471 This pragma must appear as the first line of a source file.
3472 @var{integer_literal} is the logical line number of the line following
3473 the pragma line (for use in error messages and debugging
3474 information). @var{string_literal} is a static string constant that
3475 specifies the file name to be used in error messages and debugging
3476 information. This is most notably used for the output of @code{gnatchop}
3477 with the @code{-r} switch, to make sure that the original unchopped
3478 source file is the one referred to.
3480 The second argument must be a string literal, it cannot be a static
3481 string expression other than a string literal. This is because its value
3482 is needed for error messages issued by all phases of the compiler.
3484 @node Pragma Stream_Convert
3485 @unnumberedsec Pragma Stream_Convert
3486 @findex Stream_Convert
3490 @smallexample @c ada
3491 pragma Stream_Convert (
3492 [Entity =>] type_local_NAME,
3493 [Read =>] function_NAME,
3494 [Write =>] function_NAME);
3498 This pragma provides an efficient way of providing stream functions for
3499 types defined in packages. Not only is it simpler to use than declaring
3500 the necessary functions with attribute representation clauses, but more
3501 significantly, it allows the declaration to made in such a way that the
3502 stream packages are not loaded unless they are needed. The use of
3503 the Stream_Convert pragma adds no overhead at all, unless the stream
3504 attributes are actually used on the designated type.
3506 The first argument specifies the type for which stream functions are
3507 provided. The second parameter provides a function used to read values
3508 of this type. It must name a function whose argument type may be any
3509 subtype, and whose returned type must be the type given as the first
3510 argument to the pragma.
3512 The meaning of the @var{Read}
3513 parameter is that if a stream attribute directly
3514 or indirectly specifies reading of the type given as the first parameter,
3515 then a value of the type given as the argument to the Read function is
3516 read from the stream, and then the Read function is used to convert this
3517 to the required target type.
3519 Similarly the @var{Write} parameter specifies how to treat write attributes
3520 that directly or indirectly apply to the type given as the first parameter.
3521 It must have an input parameter of the type specified by the first parameter,
3522 and the return type must be the same as the input type of the Read function.
3523 The effect is to first call the Write function to convert to the given stream
3524 type, and then write the result type to the stream.
3526 The Read and Write functions must not be overloaded subprograms. If necessary
3527 renamings can be supplied to meet this requirement.
3528 The usage of this attribute is best illustrated by a simple example, taken
3529 from the GNAT implementation of package Ada.Strings.Unbounded:
3531 @smallexample @c ada
3532 function To_Unbounded (S : String)
3533 return Unbounded_String
3534 renames To_Unbounded_String;
3536 pragma Stream_Convert
3537 (Unbounded_String, To_Unbounded, To_String);
3541 The specifications of the referenced functions, as given in the Ada 95
3542 Reference Manual are:
3544 @smallexample @c ada
3545 function To_Unbounded_String (Source : String)
3546 return Unbounded_String;
3548 function To_String (Source : Unbounded_String)
3553 The effect is that if the value of an unbounded string is written to a
3554 stream, then the representation of the item in the stream is in the same
3555 format used for @code{Standard.String}, and this same representation is
3556 expected when a value of this type is read from the stream.
3558 @node Pragma Style_Checks
3559 @unnumberedsec Pragma Style_Checks
3560 @findex Style_Checks
3564 @smallexample @c ada
3565 pragma Style_Checks (string_LITERAL | ALL_CHECKS |
3566 On | Off [, local_NAME]);
3570 This pragma is used in conjunction with compiler switches to control the
3571 built in style checking provided by GNAT@. The compiler switches, if set,
3572 provide an initial setting for the switches, and this pragma may be used
3573 to modify these settings, or the settings may be provided entirely by
3574 the use of the pragma. This pragma can be used anywhere that a pragma
3575 is legal, including use as a configuration pragma (including use in
3576 the @file{gnat.adc} file).
3578 The form with a string literal specifies which style options are to be
3579 activated. These are additive, so they apply in addition to any previously
3580 set style check options. The codes for the options are the same as those
3581 used in the @code{-gnaty} switch to @code{gcc} or @code{gnatmake}.
3582 For example the following two methods can be used to enable
3587 @smallexample @c ada
3588 pragma Style_Checks ("l");
3593 gcc -c -gnatyl @dots{}
3598 The form ALL_CHECKS activates all standard checks (its use is equivalent
3599 to the use of the @code{gnaty} switch with no options. See GNAT User's
3602 The forms with @code{Off} and @code{On}
3603 can be used to temporarily disable style checks
3604 as shown in the following example:
3606 @smallexample @c ada
3610 pragma Style_Checks ("k"); -- requires keywords in lower case
3611 pragma Style_Checks (Off); -- turn off style checks
3612 NULL; -- this will not generate an error message
3613 pragma Style_Checks (On); -- turn style checks back on
3614 NULL; -- this will generate an error message
3618 Finally the two argument form is allowed only if the first argument is
3619 @code{On} or @code{Off}. The effect is to turn of semantic style checks
3620 for the specified entity, as shown in the following example:
3622 @smallexample @c ada
3626 pragma Style_Checks ("r"); -- require consistency of identifier casing
3628 Rf1 : Integer := ARG; -- incorrect, wrong case
3629 pragma Style_Checks (Off, Arg);
3630 Rf2 : Integer := ARG; -- OK, no error
3633 @node Pragma Subtitle
3634 @unnumberedsec Pragma Subtitle
3639 @smallexample @c ada
3640 pragma Subtitle ([Subtitle =>] STRING_LITERAL);
3644 This pragma is recognized for compatibility with other Ada compilers
3645 but is ignored by GNAT@.
3647 @node Pragma Suppress_All
3648 @unnumberedsec Pragma Suppress_All
3649 @findex Suppress_All
3653 @smallexample @c ada
3654 pragma Suppress_All;
3658 This pragma can only appear immediately following a compilation
3659 unit. The effect is to apply @code{Suppress (All_Checks)} to the unit
3660 which it follows. This pragma is implemented for compatibility with DEC
3661 Ada 83 usage. The use of pragma @code{Suppress (All_Checks)} as a normal
3662 configuration pragma is the preferred usage in GNAT@.
3664 @node Pragma Suppress_Exception_Locations
3665 @unnumberedsec Pragma Suppress_Exception_Locations
3666 @findex Suppress_Exception_Locations
3670 @smallexample @c ada
3671 pragma Suppress_Exception_Locations;
3675 In normal mode, a raise statement for an exception by default generates
3676 an exception message giving the file name and line number for the location
3677 of the raise. This is useful for debugging and logging purposes, but this
3678 entails extra space for the strings for the messages. The configuration
3679 pragma @code{Suppress_Exception_Locations} can be used to suppress the
3680 generation of these strings, with the result that space is saved, but the
3681 exception message for such raises is null. This configuration pragma may
3682 appear in a global configuration pragma file, or in a specific unit as
3683 usual. It is not required that this pragma be used consistently within
3684 a partition, so it is fine to have some units within a partition compiled
3685 with this pragma and others compiled in normal mode without it.
3687 @node Pragma Suppress_Initialization
3688 @unnumberedsec Pragma Suppress_Initialization
3689 @findex Suppress_Initialization
3690 @cindex Suppressing initialization
3691 @cindex Initialization, suppression of
3695 @smallexample @c ada
3696 pragma Suppress_Initialization ([Entity =>] type_Name);
3700 This pragma suppresses any implicit or explicit initialization
3701 associated with the given type name for all variables of this type.
3703 @node Pragma Task_Info
3704 @unnumberedsec Pragma Task_Info
3709 @smallexample @c ada
3710 pragma Task_Info (EXPRESSION);
3714 This pragma appears within a task definition (like pragma
3715 @code{Priority}) and applies to the task in which it appears. The
3716 argument must be of type @code{System.Task_Info.Task_Info_Type}.
3717 The @code{Task_Info} pragma provides system dependent control over
3718 aspects of tasking implementation, for example, the ability to map
3719 tasks to specific processors. For details on the facilities available
3720 for the version of GNAT that you are using, see the documentation
3721 in the specification of package System.Task_Info in the runtime
3724 @node Pragma Task_Name
3725 @unnumberedsec Pragma Task_Name
3730 @smallexample @c ada
3731 pragma Task_Name (string_EXPRESSION);
3735 This pragma appears within a task definition (like pragma
3736 @code{Priority}) and applies to the task in which it appears. The
3737 argument must be of type String, and provides a name to be used for
3738 the task instance when the task is created. Note that this expression
3739 is not required to be static, and in particular, it can contain
3740 references to task discriminants. This facility can be used to
3741 provide different names for different tasks as they are created,
3742 as illustrated in the example below.
3744 The task name is recorded internally in the run-time structures
3745 and is accessible to tools like the debugger. In addition the
3746 routine @code{Ada.Task_Identification.Image} will return this
3747 string, with a unique task address appended.
3749 @smallexample @c ada
3750 -- Example of the use of pragma Task_Name
3752 with Ada.Task_Identification;
3753 use Ada.Task_Identification;
3754 with Text_IO; use Text_IO;
3757 type Astring is access String;
3759 task type Task_Typ (Name : access String) is
3760 pragma Task_Name (Name.all);
3763 task body Task_Typ is
3764 Nam : constant String := Image (Current_Task);
3766 Put_Line ("-->" & Nam (1 .. 14) & "<--");
3769 type Ptr_Task is access Task_Typ;
3770 Task_Var : Ptr_Task;
3774 new Task_Typ (new String'("This is task 1"));
3776 new Task_Typ (new String'("This is task 2"));
3780 @node Pragma Task_Storage
3781 @unnumberedsec Pragma Task_Storage
3782 @findex Task_Storage
3785 @smallexample @c ada
3786 pragma Task_Storage (
3787 [Task_Type =>] local_NAME,
3788 [Top_Guard =>] static_integer_EXPRESSION);
3792 This pragma specifies the length of the guard area for tasks. The guard
3793 area is an additional storage area allocated to a task. A value of zero
3794 means that either no guard area is created or a minimal guard area is
3795 created, depending on the target. This pragma can appear anywhere a
3796 @code{Storage_Size} attribute definition clause is allowed for a task
3799 @node Pragma Thread_Body
3800 @unnumberedsec Pragma Thread_Body
3804 @smallexample @c ada
3805 pragma Thread_Body (
3806 [Entity =>] local_NAME,
3807 [[Secondary_Stack_Size =>] static_integer_EXPRESSION)];
3811 This pragma specifies that the subprogram whose name is given as the
3812 @code{Entity} argument is a thread body, which will be activated
3813 by being called via its Address from foreign code. The purpose is
3814 to allow execution and registration of the foreign thread within the
3815 Ada run-time system.
3817 See the library unit @code{System.Threads} for details on the expansion of
3818 a thread body subprogram, including the calls made to subprograms
3819 within System.Threads to register the task. This unit also lists the
3820 targets and runtime systems for which this pragma is supported.
3822 A thread body subprogram may not be called directly from Ada code, and
3823 it is not permitted to apply the Access (or Unrestricted_Access) attributes
3824 to such a subprogram. The only legitimate way of calling such a subprogram
3825 is to pass its Address to foreign code and then make the call from the
3828 A thread body subprogram may have any parameters, and it may be a function
3829 returning a result. The convention of the thread body subprogram may be
3830 set in the usual manner using @code{pragma Convention}.
3832 The secondary stack size parameter, if given, is used to set the size
3833 of secondary stack for the thread. The secondary stack is allocated as
3834 a local variable of the expanded thread body subprogram, and thus is
3835 allocated out of the main thread stack size. If no secondary stack
3836 size parameter is present, the default size (from the declaration in
3837 @code{System.Secondary_Stack} is used.
3839 @node Pragma Time_Slice
3840 @unnumberedsec Pragma Time_Slice
3845 @smallexample @c ada
3846 pragma Time_Slice (static_duration_EXPRESSION);
3850 For implementations of GNAT on operating systems where it is possible
3851 to supply a time slice value, this pragma may be used for this purpose.
3852 It is ignored if it is used in a system that does not allow this control,
3853 or if it appears in other than the main program unit.
3855 Note that the effect of this pragma is identical to the effect of the
3856 DEC Ada 83 pragma of the same name when operating under OpenVMS systems.
3859 @unnumberedsec Pragma Title
3864 @smallexample @c ada
3865 pragma Title (TITLING_OPTION [, TITLING OPTION]);
3868 [Title =>] STRING_LITERAL,
3869 | [Subtitle =>] STRING_LITERAL
3873 Syntax checked but otherwise ignored by GNAT@. This is a listing control
3874 pragma used in DEC Ada 83 implementations to provide a title and/or
3875 subtitle for the program listing. The program listing generated by GNAT
3876 does not have titles or subtitles.
3878 Unlike other pragmas, the full flexibility of named notation is allowed
3879 for this pragma, i.e.@: the parameters may be given in any order if named
3880 notation is used, and named and positional notation can be mixed
3881 following the normal rules for procedure calls in Ada.
3883 @node Pragma Unchecked_Union
3884 @unnumberedsec Pragma Unchecked_Union
3886 @findex Unchecked_Union
3890 @smallexample @c ada
3891 pragma Unchecked_Union (first_subtype_local_NAME);
3895 This pragma is used to declare that the specified type should be represented
3897 equivalent to a C union type, and is intended only for use in
3898 interfacing with C code that uses union types. In Ada terms, the named
3899 type must obey the following rules:
3903 It is a non-tagged non-limited record type.
3905 It has a single discrete discriminant with a default value.
3907 The component list consists of a single variant part.
3909 Each variant has a component list with a single component.
3911 No nested variants are allowed.
3913 No component has an explicit default value.
3915 No component has a non-static constraint.
3919 In addition, given a type that meets the above requirements, the
3920 following restrictions apply to its use throughout the program:
3924 The discriminant name can be mentioned only in an aggregate.
3926 No subtypes may be created of this type.
3928 The type may not be constrained by giving a discriminant value.
3930 The type cannot be passed as the actual for a generic formal with a
3935 Equality and inequality operations on @code{unchecked_unions} are not
3936 available, since there is no discriminant to compare and the compiler
3937 does not even know how many bits to compare. It is implementation
3938 dependent whether this is detected at compile time as an illegality or
3939 whether it is undetected and considered to be an erroneous construct. In
3940 GNAT, a direct comparison is illegal, but GNAT does not attempt to catch
3941 the composite case (where two composites are compared that contain an
3942 unchecked union component), so such comparisons are simply considered
3945 The layout of the resulting type corresponds exactly to a C union, where
3946 each branch of the union corresponds to a single variant in the Ada
3947 record. The semantics of the Ada program is not changed in any way by
3948 the pragma, i.e.@: provided the above restrictions are followed, and no
3949 erroneous incorrect references to fields or erroneous comparisons occur,
3950 the semantics is exactly as described by the Ada reference manual.
3951 Pragma @code{Suppress (Discriminant_Check)} applies implicitly to the
3952 type and the default convention is C.
3954 @node Pragma Unimplemented_Unit
3955 @unnumberedsec Pragma Unimplemented_Unit
3956 @findex Unimplemented_Unit
3960 @smallexample @c ada
3961 pragma Unimplemented_Unit;
3965 If this pragma occurs in a unit that is processed by the compiler, GNAT
3966 aborts with the message @samp{@var{xxx} not implemented}, where
3967 @var{xxx} is the name of the current compilation unit. This pragma is
3968 intended to allow the compiler to handle unimplemented library units in
3971 The abort only happens if code is being generated. Thus you can use
3972 specs of unimplemented packages in syntax or semantic checking mode.
3974 @node Pragma Universal_Data
3975 @unnumberedsec Pragma Universal_Data
3976 @findex Universal_Data
3980 @smallexample @c ada
3981 pragma Universal_Data [(library_unit_Name)];
3985 This pragma is supported only for the AAMP target and is ignored for
3986 other targets. The pragma specifies that all library-level objects
3987 (Counter 0 data) associated with the library unit are to be accessed
3988 and updated using universal addressing (24-bit addresses for AAMP5)
3989 rather than the default of 16-bit Data Environment (DENV) addressing.
3990 Use of this pragma will generally result in less efficient code for
3991 references to global data associated with the library unit, but
3992 allows such data to be located anywhere in memory. This pragma is
3993 a library unit pragma, but can also be used as a configuration pragma
3994 (including use in the @file{gnat.adc} file). The functionality
3995 of this pragma is also available by applying the -univ switch on the
3996 compilations of units where universal addressing of the data is desired.
3998 @node Pragma Unreferenced
3999 @unnumberedsec Pragma Unreferenced
4000 @findex Unreferenced
4001 @cindex Warnings, unreferenced
4005 @smallexample @c ada
4006 pragma Unreferenced (local_NAME @{, local_NAME@});
4010 This pragma signals that the entities whose names are listed are
4011 deliberately not referenced in the current source unit. This
4012 suppresses warnings about the
4013 entities being unreferenced, and in addition a warning will be
4014 generated if one of these entities is in fact referenced in the
4015 same unit as the pragma (or in the corresponding body, or one
4018 This is particularly useful for clearly signaling that a particular
4019 parameter is not referenced in some particular subprogram implementation
4020 and that this is deliberate. It can also be useful in the case of
4021 objects declared only for their initialization or finalization side
4024 If @code{local_NAME} identifies more than one matching homonym in the
4025 current scope, then the entity most recently declared is the one to which
4028 The left hand side of an assignment does not count as a reference for the
4029 purpose of this pragma. Thus it is fine to assign to an entity for which
4030 pragma Unreferenced is given.
4032 Note that if a warning is desired for all calls to a given subprogram,
4033 regardless of whether they occur in the same unit as the subprogram
4034 declaration, then this pragma should not be used (calls from another
4035 unit would not be flagged); pragma Obsolescent can be used instead
4036 for this purpose (@xref{Pragma Obsolescent}).
4038 @node Pragma Unreserve_All_Interrupts
4039 @unnumberedsec Pragma Unreserve_All_Interrupts
4040 @findex Unreserve_All_Interrupts
4044 @smallexample @c ada
4045 pragma Unreserve_All_Interrupts;
4049 Normally certain interrupts are reserved to the implementation. Any attempt
4050 to attach an interrupt causes Program_Error to be raised, as described in
4051 RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
4052 many systems for a @kbd{Ctrl-C} interrupt. Normally this interrupt is
4053 reserved to the implementation, so that @kbd{Ctrl-C} can be used to
4054 interrupt execution.
4056 If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in
4057 a program, then all such interrupts are unreserved. This allows the
4058 program to handle these interrupts, but disables their standard
4059 functions. For example, if this pragma is used, then pressing
4060 @kbd{Ctrl-C} will not automatically interrupt execution. However,
4061 a program can then handle the @code{SIGINT} interrupt as it chooses.
4063 For a full list of the interrupts handled in a specific implementation,
4064 see the source code for the specification of @code{Ada.Interrupts.Names} in
4065 file @file{a-intnam.ads}. This is a target dependent file that contains the
4066 list of interrupts recognized for a given target. The documentation in
4067 this file also specifies what interrupts are affected by the use of
4068 the @code{Unreserve_All_Interrupts} pragma.
4070 For a more general facility for controlling what interrupts can be
4071 handled, see pragma @code{Interrupt_State}, which subsumes the functionality
4072 of the @code{Unreserve_All_Interrupts} pragma.
4074 @node Pragma Unsuppress
4075 @unnumberedsec Pragma Unsuppress
4080 @smallexample @c ada
4081 pragma Unsuppress (IDENTIFIER [, [On =>] NAME]);
4085 This pragma undoes the effect of a previous pragma @code{Suppress}. If
4086 there is no corresponding pragma @code{Suppress} in effect, it has no
4087 effect. The range of the effect is the same as for pragma
4088 @code{Suppress}. The meaning of the arguments is identical to that used
4089 in pragma @code{Suppress}.
4091 One important application is to ensure that checks are on in cases where
4092 code depends on the checks for its correct functioning, so that the code
4093 will compile correctly even if the compiler switches are set to suppress
4096 @node Pragma Use_VADS_Size
4097 @unnumberedsec Pragma Use_VADS_Size
4098 @cindex @code{Size}, VADS compatibility
4099 @findex Use_VADS_Size
4103 @smallexample @c ada
4104 pragma Use_VADS_Size;
4108 This is a configuration pragma. In a unit to which it applies, any use
4109 of the 'Size attribute is automatically interpreted as a use of the
4110 'VADS_Size attribute. Note that this may result in incorrect semantic
4111 processing of valid Ada 95 programs. This is intended to aid in the
4112 handling of legacy code which depends on the interpretation of Size
4113 as implemented in the VADS compiler. See description of the VADS_Size
4114 attribute for further details.
4116 @node Pragma Validity_Checks
4117 @unnumberedsec Pragma Validity_Checks
4118 @findex Validity_Checks
4122 @smallexample @c ada
4123 pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off);
4127 This pragma is used in conjunction with compiler switches to control the
4128 built-in validity checking provided by GNAT@. The compiler switches, if set
4129 provide an initial setting for the switches, and this pragma may be used
4130 to modify these settings, or the settings may be provided entirely by
4131 the use of the pragma. This pragma can be used anywhere that a pragma
4132 is legal, including use as a configuration pragma (including use in
4133 the @file{gnat.adc} file).
4135 The form with a string literal specifies which validity options are to be
4136 activated. The validity checks are first set to include only the default
4137 reference manual settings, and then a string of letters in the string
4138 specifies the exact set of options required. The form of this string
4139 is exactly as described for the @code{-gnatVx} compiler switch (see the
4140 GNAT users guide for details). For example the following two methods
4141 can be used to enable validity checking for mode @code{in} and
4142 @code{in out} subprogram parameters:
4146 @smallexample @c ada
4147 pragma Validity_Checks ("im");
4152 gcc -c -gnatVim @dots{}
4157 The form ALL_CHECKS activates all standard checks (its use is equivalent
4158 to the use of the @code{gnatva} switch.
4160 The forms with @code{Off} and @code{On}
4161 can be used to temporarily disable validity checks
4162 as shown in the following example:
4164 @smallexample @c ada
4168 pragma Validity_Checks ("c"); -- validity checks for copies
4169 pragma Validity_Checks (Off); -- turn off validity checks
4170 A := B; -- B will not be validity checked
4171 pragma Validity_Checks (On); -- turn validity checks back on
4172 A := C; -- C will be validity checked
4175 @node Pragma Volatile
4176 @unnumberedsec Pragma Volatile
4181 @smallexample @c ada
4182 pragma Volatile (local_NAME);
4186 This pragma is defined by the Ada 95 Reference Manual, and the GNAT
4187 implementation is fully conformant with this definition. The reason it
4188 is mentioned in this section is that a pragma of the same name was supplied
4189 in some Ada 83 compilers, including DEC Ada 83. The Ada 95 implementation
4190 of pragma Volatile is upwards compatible with the implementation in
4193 @node Pragma Warnings
4194 @unnumberedsec Pragma Warnings
4199 @smallexample @c ada
4200 pragma Warnings (On | Off [, local_NAME]);
4204 Normally warnings are enabled, with the output being controlled by
4205 the command line switch. Warnings (@code{Off}) turns off generation of
4206 warnings until a Warnings (@code{On}) is encountered or the end of the
4207 current unit. If generation of warnings is turned off using this
4208 pragma, then no warning messages are output, regardless of the
4209 setting of the command line switches.
4211 The form with a single argument is a configuration pragma.
4213 If the @var{local_NAME} parameter is present, warnings are suppressed for
4214 the specified entity. This suppression is effective from the point where
4215 it occurs till the end of the extended scope of the variable (similar to
4216 the scope of @code{Suppress}).
4218 @node Pragma Weak_External
4219 @unnumberedsec Pragma Weak_External
4220 @findex Weak_External
4224 @smallexample @c ada
4225 pragma Weak_External ([Entity =>] local_NAME);
4229 @var{local_NAME} must refer to an object that is declared at the library
4230 level. This pragma specifies that the given entity should be marked as a
4231 weak symbol for the linker. It is equivalent to @code{__attribute__((weak))}
4232 in GNU C and causes @var{local_NAME} to be emitted as a weak symbol instead
4233 of a regular symbol, that is to say a symbol that does not have to be
4234 resolved by the linker if used in conjunction with a pragma Import.
4236 When a weak symbol is not resolved by the linker, its address is set to
4237 zero. This is useful in writing interfaces to external modules that may
4238 or may not be linked in the final executable, for example depending on
4239 configuration settings.
4241 If a program references at run time an entity to which this pragma has been
4242 applied, and the corresponding symbol was not resolved at link time, then
4243 the execution of the program is erroneous. It is not erroneous to take the
4244 Address of such an entity, for example to guard potential references,
4245 as shown in the example below.
4247 Some file formats do not support weak symbols so not all target machines
4248 support this pragma.
4250 @smallexample @c ada
4251 -- Example of the use of pragma Weak_External
4253 package External_Module is
4255 pragma Import (C, key);
4256 pragma Weak_External (key);
4257 function Present return boolean;
4258 end External_Module;
4260 with System; use System;
4261 package body External_Module is
4262 function Present return boolean is
4264 return key'Address /= System.Null_Address;
4266 end External_Module;
4269 @node Implementation Defined Attributes
4270 @chapter Implementation Defined Attributes
4271 Ada 95 defines (throughout the Ada 95 reference manual,
4272 summarized in annex K),
4273 a set of attributes that provide useful additional functionality in all
4274 areas of the language. These language defined attributes are implemented
4275 in GNAT and work as described in the Ada 95 Reference Manual.
4277 In addition, Ada 95 allows implementations to define additional
4278 attributes whose meaning is defined by the implementation. GNAT provides
4279 a number of these implementation-dependent attributes which can be used
4280 to extend and enhance the functionality of the compiler. This section of
4281 the GNAT reference manual describes these additional attributes.
4283 Note that any program using these attributes may not be portable to
4284 other compilers (although GNAT implements this set of attributes on all
4285 platforms). Therefore if portability to other compilers is an important
4286 consideration, you should minimize the use of these attributes.
4297 * Default_Bit_Order::
4305 * Has_Access_Values::
4306 * Has_Discriminants::
4312 * Max_Interrupt_Priority::
4314 * Maximum_Alignment::
4318 * Passed_By_Reference::
4329 * Unconstrained_Array::
4330 * Universal_Literal_String::
4331 * Unrestricted_Access::
4339 @unnumberedsec Abort_Signal
4340 @findex Abort_Signal
4342 @code{Standard'Abort_Signal} (@code{Standard} is the only allowed
4343 prefix) provides the entity for the special exception used to signal
4344 task abort or asynchronous transfer of control. Normally this attribute
4345 should only be used in the tasking runtime (it is highly peculiar, and
4346 completely outside the normal semantics of Ada, for a user program to
4347 intercept the abort exception).
4350 @unnumberedsec Address_Size
4351 @cindex Size of @code{Address}
4352 @findex Address_Size
4354 @code{Standard'Address_Size} (@code{Standard} is the only allowed
4355 prefix) is a static constant giving the number of bits in an
4356 @code{Address}. It is the same value as System.Address'Size,
4357 but has the advantage of being static, while a direct
4358 reference to System.Address'Size is non-static because Address
4362 @unnumberedsec Asm_Input
4365 The @code{Asm_Input} attribute denotes a function that takes two
4366 parameters. The first is a string, the second is an expression of the
4367 type designated by the prefix. The first (string) argument is required
4368 to be a static expression, and is the constraint for the parameter,
4369 (e.g.@: what kind of register is required). The second argument is the
4370 value to be used as the input argument. The possible values for the
4371 constant are the same as those used in the RTL, and are dependent on
4372 the configuration file used to built the GCC back end.
4373 @ref{Machine Code Insertions}
4376 @unnumberedsec Asm_Output
4379 The @code{Asm_Output} attribute denotes a function that takes two
4380 parameters. The first is a string, the second is the name of a variable
4381 of the type designated by the attribute prefix. The first (string)
4382 argument is required to be a static expression and designates the
4383 constraint for the parameter (e.g.@: what kind of register is
4384 required). The second argument is the variable to be updated with the
4385 result. The possible values for constraint are the same as those used in
4386 the RTL, and are dependent on the configuration file used to build the
4387 GCC back end. If there are no output operands, then this argument may
4388 either be omitted, or explicitly given as @code{No_Output_Operands}.
4389 @ref{Machine Code Insertions}
4392 @unnumberedsec AST_Entry
4396 This attribute is implemented only in OpenVMS versions of GNAT@. Applied to
4397 the name of an entry, it yields a value of the predefined type AST_Handler
4398 (declared in the predefined package System, as extended by the use of
4399 pragma @code{Extend_System (Aux_DEC)}). This value enables the given entry to
4400 be called when an AST occurs. For further details, refer to the @cite{DEC Ada
4401 Language Reference Manual}, section 9.12a.
4406 @code{@var{obj}'Bit}, where @var{obj} is any object, yields the bit
4407 offset within the storage unit (byte) that contains the first bit of
4408 storage allocated for the object. The value of this attribute is of the
4409 type @code{Universal_Integer}, and is always a non-negative number not
4410 exceeding the value of @code{System.Storage_Unit}.
4412 For an object that is a variable or a constant allocated in a register,
4413 the value is zero. (The use of this attribute does not force the
4414 allocation of a variable to memory).
4416 For an object that is a formal parameter, this attribute applies
4417 to either the matching actual parameter or to a copy of the
4418 matching actual parameter.
4420 For an access object the value is zero. Note that
4421 @code{@var{obj}.all'Bit} is subject to an @code{Access_Check} for the
4422 designated object. Similarly for a record component
4423 @code{@var{X}.@var{C}'Bit} is subject to a discriminant check and
4424 @code{@var{X}(@var{I}).Bit} and @code{@var{X}(@var{I1}..@var{I2})'Bit}
4425 are subject to index checks.
4427 This attribute is designed to be compatible with the DEC Ada 83 definition
4428 and implementation of the @code{Bit} attribute.
4431 @unnumberedsec Bit_Position
4432 @findex Bit_Position
4434 @code{@var{R.C}'Bit}, where @var{R} is a record object and C is one
4435 of the fields of the record type, yields the bit
4436 offset within the record contains the first bit of
4437 storage allocated for the object. The value of this attribute is of the
4438 type @code{Universal_Integer}. The value depends only on the field
4439 @var{C} and is independent of the alignment of
4440 the containing record @var{R}.
4443 @unnumberedsec Code_Address
4444 @findex Code_Address
4445 @cindex Subprogram address
4446 @cindex Address of subprogram code
4449 attribute may be applied to subprograms in Ada 95, but the
4450 intended effect from the Ada 95 reference manual seems to be to provide
4451 an address value which can be used to call the subprogram by means of
4452 an address clause as in the following example:
4454 @smallexample @c ada
4455 procedure K is @dots{}
4458 for L'Address use K'Address;
4459 pragma Import (Ada, L);
4463 A call to @code{L} is then expected to result in a call to @code{K}@.
4464 In Ada 83, where there were no access-to-subprogram values, this was
4465 a common work around for getting the effect of an indirect call.
4466 GNAT implements the above use of @code{Address} and the technique
4467 illustrated by the example code works correctly.
4469 However, for some purposes, it is useful to have the address of the start
4470 of the generated code for the subprogram. On some architectures, this is
4471 not necessarily the same as the @code{Address} value described above.
4472 For example, the @code{Address} value may reference a subprogram
4473 descriptor rather than the subprogram itself.
4475 The @code{'Code_Address} attribute, which can only be applied to
4476 subprogram entities, always returns the address of the start of the
4477 generated code of the specified subprogram, which may or may not be
4478 the same value as is returned by the corresponding @code{'Address}
4481 @node Default_Bit_Order
4482 @unnumberedsec Default_Bit_Order
4484 @cindex Little endian
4485 @findex Default_Bit_Order
4487 @code{Standard'Default_Bit_Order} (@code{Standard} is the only
4488 permissible prefix), provides the value @code{System.Default_Bit_Order}
4489 as a @code{Pos} value (0 for @code{High_Order_First}, 1 for
4490 @code{Low_Order_First}). This is used to construct the definition of
4491 @code{Default_Bit_Order} in package @code{System}.
4494 @unnumberedsec Elaborated
4497 The prefix of the @code{'Elaborated} attribute must be a unit name. The
4498 value is a Boolean which indicates whether or not the given unit has been
4499 elaborated. This attribute is primarily intended for internal use by the
4500 generated code for dynamic elaboration checking, but it can also be used
4501 in user programs. The value will always be True once elaboration of all
4502 units has been completed. An exception is for units which need no
4503 elaboration, the value is always False for such units.
4506 @unnumberedsec Elab_Body
4509 This attribute can only be applied to a program unit name. It returns
4510 the entity for the corresponding elaboration procedure for elaborating
4511 the body of the referenced unit. This is used in the main generated
4512 elaboration procedure by the binder and is not normally used in any
4513 other context. However, there may be specialized situations in which it
4514 is useful to be able to call this elaboration procedure from Ada code,
4515 e.g.@: if it is necessary to do selective re-elaboration to fix some
4519 @unnumberedsec Elab_Spec
4522 This attribute can only be applied to a program unit name. It returns
4523 the entity for the corresponding elaboration procedure for elaborating
4524 the specification of the referenced unit. This is used in the main
4525 generated elaboration procedure by the binder and is not normally used
4526 in any other context. However, there may be specialized situations in
4527 which it is useful to be able to call this elaboration procedure from
4528 Ada code, e.g.@: if it is necessary to do selective re-elaboration to fix
4533 @cindex Ada 83 attributes
4536 The @code{Emax} attribute is provided for compatibility with Ada 83. See
4537 the Ada 83 reference manual for an exact description of the semantics of
4541 @unnumberedsec Enum_Rep
4542 @cindex Representation of enums
4545 For every enumeration subtype @var{S}, @code{@var{S}'Enum_Rep} denotes a
4546 function with the following spec:
4548 @smallexample @c ada
4549 function @var{S}'Enum_Rep (Arg : @var{S}'Base)
4550 return @i{Universal_Integer};
4554 It is also allowable to apply @code{Enum_Rep} directly to an object of an
4555 enumeration type or to a non-overloaded enumeration
4556 literal. In this case @code{@var{S}'Enum_Rep} is equivalent to
4557 @code{@var{typ}'Enum_Rep(@var{S})} where @var{typ} is the type of the
4558 enumeration literal or object.
4560 The function returns the representation value for the given enumeration
4561 value. This will be equal to value of the @code{Pos} attribute in the
4562 absence of an enumeration representation clause. This is a static
4563 attribute (i.e.@: the result is static if the argument is static).
4565 @code{@var{S}'Enum_Rep} can also be used with integer types and objects,
4566 in which case it simply returns the integer value. The reason for this
4567 is to allow it to be used for @code{(<>)} discrete formal arguments in
4568 a generic unit that can be instantiated with either enumeration types
4569 or integer types. Note that if @code{Enum_Rep} is used on a modular
4570 type whose upper bound exceeds the upper bound of the largest signed
4571 integer type, and the argument is a variable, so that the universal
4572 integer calculation is done at run-time, then the call to @code{Enum_Rep}
4573 may raise @code{Constraint_Error}.
4576 @unnumberedsec Epsilon
4577 @cindex Ada 83 attributes
4580 The @code{Epsilon} attribute is provided for compatibility with Ada 83. See
4581 the Ada 83 reference manual for an exact description of the semantics of
4585 @unnumberedsec Fixed_Value
4588 For every fixed-point type @var{S}, @code{@var{S}'Fixed_Value} denotes a
4589 function with the following specification:
4591 @smallexample @c ada
4592 function @var{S}'Fixed_Value (Arg : @i{Universal_Integer})
4597 The value returned is the fixed-point value @var{V} such that
4599 @smallexample @c ada
4600 @var{V} = Arg * @var{S}'Small
4604 The effect is thus similar to first converting the argument to the
4605 integer type used to represent @var{S}, and then doing an unchecked
4606 conversion to the fixed-point type. The difference is
4607 that there are full range checks, to ensure that the result is in range.
4608 This attribute is primarily intended for use in implementation of the
4609 input-output functions for fixed-point values.
4611 @node Has_Access_Values
4612 @unnumberedsec Has_Access_Values
4613 @cindex Access values, testing for
4614 @findex Has_Access_Values
4616 The prefix of the @code{Has_Access_Values} attribute is a type. The result
4617 is a Boolean value which is True if the is an access type, or is a composite
4618 type with a component (at any nesting depth) that is an access type, and is
4620 The intended use of this attribute is in conjunction with generic
4621 definitions. If the attribute is applied to a generic private type, it
4622 indicates whether or not the corresponding actual type has access values.
4624 @node Has_Discriminants
4625 @unnumberedsec Has_Discriminants
4626 @cindex Discriminants, testing for
4627 @findex Has_Discriminants
4629 The prefix of the @code{Has_Discriminants} attribute is a type. The result
4630 is a Boolean value which is True if the type has discriminants, and False
4631 otherwise. The intended use of this attribute is in conjunction with generic
4632 definitions. If the attribute is applied to a generic private type, it
4633 indicates whether or not the corresponding actual type has discriminants.
4639 The @code{Img} attribute differs from @code{Image} in that it may be
4640 applied to objects as well as types, in which case it gives the
4641 @code{Image} for the subtype of the object. This is convenient for
4644 @smallexample @c ada
4645 Put_Line ("X = " & X'Img);
4649 has the same meaning as the more verbose:
4651 @smallexample @c ada
4652 Put_Line ("X = " & @var{T}'Image (X));
4656 where @var{T} is the (sub)type of the object @code{X}.
4659 @unnumberedsec Integer_Value
4660 @findex Integer_Value
4662 For every integer type @var{S}, @code{@var{S}'Integer_Value} denotes a
4663 function with the following spec:
4665 @smallexample @c ada
4666 function @var{S}'Integer_Value (Arg : @i{Universal_Fixed})
4671 The value returned is the integer value @var{V}, such that
4673 @smallexample @c ada
4674 Arg = @var{V} * @var{T}'Small
4678 where @var{T} is the type of @code{Arg}.
4679 The effect is thus similar to first doing an unchecked conversion from
4680 the fixed-point type to its corresponding implementation type, and then
4681 converting the result to the target integer 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 standard input-output functions for fixed-point values.
4687 @unnumberedsec Large
4688 @cindex Ada 83 attributes
4691 The @code{Large} attribute is provided for compatibility with Ada 83. See
4692 the Ada 83 reference manual for an exact description of the semantics of
4696 @unnumberedsec Machine_Size
4697 @findex Machine_Size
4699 This attribute is identical to the @code{Object_Size} attribute. It is
4700 provided for compatibility with the DEC Ada 83 attribute of this name.
4703 @unnumberedsec Mantissa
4704 @cindex Ada 83 attributes
4707 The @code{Mantissa} attribute is provided for compatibility with Ada 83. See
4708 the Ada 83 reference manual for an exact description of the semantics of
4711 @node Max_Interrupt_Priority
4712 @unnumberedsec Max_Interrupt_Priority
4713 @cindex Interrupt priority, maximum
4714 @findex Max_Interrupt_Priority
4716 @code{Standard'Max_Interrupt_Priority} (@code{Standard} is the only
4717 permissible prefix), provides the same value as
4718 @code{System.Max_Interrupt_Priority}.
4721 @unnumberedsec Max_Priority
4722 @cindex Priority, maximum
4723 @findex Max_Priority
4725 @code{Standard'Max_Priority} (@code{Standard} is the only permissible
4726 prefix) provides the same value as @code{System.Max_Priority}.
4728 @node Maximum_Alignment
4729 @unnumberedsec Maximum_Alignment
4730 @cindex Alignment, maximum
4731 @findex Maximum_Alignment
4733 @code{Standard'Maximum_Alignment} (@code{Standard} is the only
4734 permissible prefix) provides the maximum useful alignment value for the
4735 target. This is a static value that can be used to specify the alignment
4736 for an object, guaranteeing that it is properly aligned in all
4739 @node Mechanism_Code
4740 @unnumberedsec Mechanism_Code
4741 @cindex Return values, passing mechanism
4742 @cindex Parameters, passing mechanism
4743 @findex Mechanism_Code
4745 @code{@var{function}'Mechanism_Code} yields an integer code for the
4746 mechanism used for the result of function, and
4747 @code{@var{subprogram}'Mechanism_Code (@var{n})} yields the mechanism
4748 used for formal parameter number @var{n} (a static integer value with 1
4749 meaning the first parameter) of @var{subprogram}. The code returned is:
4757 by descriptor (default descriptor class)
4759 by descriptor (UBS: unaligned bit string)
4761 by descriptor (UBSB: aligned bit string with arbitrary bounds)
4763 by descriptor (UBA: unaligned bit array)
4765 by descriptor (S: string, also scalar access type parameter)
4767 by descriptor (SB: string with arbitrary bounds)
4769 by descriptor (A: contiguous array)
4771 by descriptor (NCA: non-contiguous array)
4775 Values from 3 through 10 are only relevant to Digital OpenVMS implementations.
4778 @node Null_Parameter
4779 @unnumberedsec Null_Parameter
4780 @cindex Zero address, passing
4781 @findex Null_Parameter
4783 A reference @code{@var{T}'Null_Parameter} denotes an imaginary object of
4784 type or subtype @var{T} allocated at machine address zero. The attribute
4785 is allowed only as the default expression of a formal parameter, or as
4786 an actual expression of a subprogram call. In either case, the
4787 subprogram must be imported.
4789 The identity of the object is represented by the address zero in the
4790 argument list, independent of the passing mechanism (explicit or
4793 This capability is needed to specify that a zero address should be
4794 passed for a record or other composite object passed by reference.
4795 There is no way of indicating this without the @code{Null_Parameter}
4799 @unnumberedsec Object_Size
4800 @cindex Size, used for objects
4803 The size of an object is not necessarily the same as the size of the type
4804 of an object. This is because by default object sizes are increased to be
4805 a multiple of the alignment of the object. For example,
4806 @code{Natural'Size} is
4807 31, but by default objects of type @code{Natural} will have a size of 32 bits.
4808 Similarly, a record containing an integer and a character:
4810 @smallexample @c ada
4818 will have a size of 40 (that is @code{Rec'Size} will be 40. The
4819 alignment will be 4, because of the
4820 integer field, and so the default size of record objects for this type
4821 will be 64 (8 bytes).
4823 The @code{@var{type}'Object_Size} attribute
4824 has been added to GNAT to allow the
4825 default object size of a type to be easily determined. For example,
4826 @code{Natural'Object_Size} is 32, and
4827 @code{Rec'Object_Size} (for the record type in the above example) will be
4828 64. Note also that, unlike the situation with the
4829 @code{Size} attribute as defined in the Ada RM, the
4830 @code{Object_Size} attribute can be specified individually
4831 for different subtypes. For example:
4833 @smallexample @c ada
4834 type R is new Integer;
4835 subtype R1 is R range 1 .. 10;
4836 subtype R2 is R range 1 .. 10;
4837 for R2'Object_Size use 8;
4841 In this example, @code{R'Object_Size} and @code{R1'Object_Size} are both
4842 32 since the default object size for a subtype is the same as the object size
4843 for the parent subtype. This means that objects of type @code{R}
4845 by default be 32 bits (four bytes). But objects of type
4846 @code{R2} will be only
4847 8 bits (one byte), since @code{R2'Object_Size} has been set to 8.
4849 @node Passed_By_Reference
4850 @unnumberedsec Passed_By_Reference
4851 @cindex Parameters, when passed by reference
4852 @findex Passed_By_Reference
4854 @code{@var{type}'Passed_By_Reference} for any subtype @var{type} returns
4855 a value of type @code{Boolean} value that is @code{True} if the type is
4856 normally passed by reference and @code{False} if the type is normally
4857 passed by copy in calls. For scalar types, the result is always @code{False}
4858 and is static. For non-scalar types, the result is non-static.
4861 @unnumberedsec Range_Length
4862 @findex Range_Length
4864 @code{@var{type}'Range_Length} for any discrete type @var{type} yields
4865 the number of values represented by the subtype (zero for a null
4866 range). The result is static for static subtypes. @code{Range_Length}
4867 applied to the index subtype of a one dimensional array always gives the
4868 same result as @code{Range} applied to the array itself.
4871 @unnumberedsec Safe_Emax
4872 @cindex Ada 83 attributes
4875 The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See
4876 the Ada 83 reference manual for an exact description of the semantics of
4880 @unnumberedsec Safe_Large
4881 @cindex Ada 83 attributes
4884 The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See
4885 the Ada 83 reference manual for an exact description of the semantics of
4889 @unnumberedsec Small
4890 @cindex Ada 83 attributes
4893 The @code{Small} attribute is defined in Ada 95 only for fixed-point types.
4894 GNAT also allows this attribute to be applied to floating-point types
4895 for compatibility with Ada 83. See
4896 the Ada 83 reference manual for an exact description of the semantics of
4897 this attribute when applied to floating-point types.
4900 @unnumberedsec Storage_Unit
4901 @findex Storage_Unit
4903 @code{Standard'Storage_Unit} (@code{Standard} is the only permissible
4904 prefix) provides the same value as @code{System.Storage_Unit}.
4907 @unnumberedsec Target_Name
4910 @code{Standard'Target_Name} (@code{Standard} is the only permissible
4911 prefix) provides a static string value that identifies the target
4912 for the current compilation. For GCC implementations, this is the
4913 standard gcc target name without the terminating slash (for
4914 example, GNAT 5.0 on windows yields "i586-pc-mingw32msv").
4920 @code{Standard'Tick} (@code{Standard} is the only permissible prefix)
4921 provides the same value as @code{System.Tick},
4924 @unnumberedsec To_Address
4927 The @code{System'To_Address}
4928 (@code{System} is the only permissible prefix)
4929 denotes a function identical to
4930 @code{System.Storage_Elements.To_Address} except that
4931 it is a static attribute. This means that if its argument is
4932 a static expression, then the result of the attribute is a
4933 static expression. The result is that such an expression can be
4934 used in contexts (e.g.@: preelaborable packages) which require a
4935 static expression and where the function call could not be used
4936 (since the function call is always non-static, even if its
4937 argument is static).
4940 @unnumberedsec Type_Class
4943 @code{@var{type}'Type_Class} for any type or subtype @var{type} yields
4944 the value of the type class for the full type of @var{type}. If
4945 @var{type} is a generic formal type, the value is the value for the
4946 corresponding actual subtype. The value of this attribute is of type
4947 @code{System.Aux_DEC.Type_Class}, which has the following definition:
4949 @smallexample @c ada
4951 (Type_Class_Enumeration,
4953 Type_Class_Fixed_Point,
4954 Type_Class_Floating_Point,
4959 Type_Class_Address);
4963 Protected types yield the value @code{Type_Class_Task}, which thus
4964 applies to all concurrent types. This attribute is designed to
4965 be compatible with the DEC Ada 83 attribute of the same name.
4968 @unnumberedsec UET_Address
4971 The @code{UET_Address} attribute can only be used for a prefix which
4972 denotes a library package. It yields the address of the unit exception
4973 table when zero cost exception handling is used. This attribute is
4974 intended only for use within the GNAT implementation. See the unit
4975 @code{Ada.Exceptions} in files @file{a-except.ads} and @file{a-except.adb}
4976 for details on how this attribute is used in the implementation.
4978 @node Unconstrained_Array
4979 @unnumberedsec Unconstrained_Array
4980 @findex Unconstrained_Array
4982 The @code{Unconstrained_Array} attribute can be used with a prefix that
4983 denotes any type or subtype. It is a static attribute that yields
4984 @code{True} if the prefix designates an unconstrained array,
4985 and @code{False} otherwise. In a generic instance, the result is
4986 still static, and yields the result of applying this test to the
4989 @node Universal_Literal_String
4990 @unnumberedsec Universal_Literal_String
4991 @cindex Named numbers, representation of
4992 @findex Universal_Literal_String
4994 The prefix of @code{Universal_Literal_String} must be a named
4995 number. The static result is the string consisting of the characters of
4996 the number as defined in the original source. This allows the user
4997 program to access the actual text of named numbers without intermediate
4998 conversions and without the need to enclose the strings in quotes (which
4999 would preclude their use as numbers). This is used internally for the
5000 construction of values of the floating-point attributes from the file
5001 @file{ttypef.ads}, but may also be used by user programs.
5003 @node Unrestricted_Access
5004 @unnumberedsec Unrestricted_Access
5005 @cindex @code{Access}, unrestricted
5006 @findex Unrestricted_Access
5008 The @code{Unrestricted_Access} attribute is similar to @code{Access}
5009 except that all accessibility and aliased view checks are omitted. This
5010 is a user-beware attribute. It is similar to
5011 @code{Address}, for which it is a desirable replacement where the value
5012 desired is an access type. In other words, its effect is identical to
5013 first applying the @code{Address} attribute and then doing an unchecked
5014 conversion to a desired access type. In GNAT, but not necessarily in
5015 other implementations, the use of static chains for inner level
5016 subprograms means that @code{Unrestricted_Access} applied to a
5017 subprogram yields a value that can be called as long as the subprogram
5018 is in scope (normal Ada 95 accessibility rules restrict this usage).
5020 It is possible to use @code{Unrestricted_Access} for any type, but care
5021 must be exercised if it is used to create pointers to unconstrained
5022 objects. In this case, the resulting pointer has the same scope as the
5023 context of the attribute, and may not be returned to some enclosing
5024 scope. For instance, a function cannot use @code{Unrestricted_Access}
5025 to create a unconstrained pointer and then return that value to the
5029 @unnumberedsec VADS_Size
5030 @cindex @code{Size}, VADS compatibility
5033 The @code{'VADS_Size} attribute is intended to make it easier to port
5034 legacy code which relies on the semantics of @code{'Size} as implemented
5035 by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the
5036 same semantic interpretation. In particular, @code{'VADS_Size} applied
5037 to a predefined or other primitive type with no Size clause yields the
5038 Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on
5039 typical machines). In addition @code{'VADS_Size} applied to an object
5040 gives the result that would be obtained by applying the attribute to
5041 the corresponding type.
5044 @unnumberedsec Value_Size
5045 @cindex @code{Size}, setting for not-first subtype
5047 @code{@var{type}'Value_Size} is the number of bits required to represent
5048 a value of the given subtype. It is the same as @code{@var{type}'Size},
5049 but, unlike @code{Size}, may be set for non-first subtypes.
5052 @unnumberedsec Wchar_T_Size
5053 @findex Wchar_T_Size
5054 @code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible
5055 prefix) provides the size in bits of the C @code{wchar_t} type
5056 primarily for constructing the definition of this type in
5057 package @code{Interfaces.C}.
5060 @unnumberedsec Word_Size
5062 @code{Standard'Word_Size} (@code{Standard} is the only permissible
5063 prefix) provides the value @code{System.Word_Size}.
5065 @c ------------------------
5066 @node Implementation Advice
5067 @chapter Implementation Advice
5069 The main text of the Ada 95 Reference Manual describes the required
5070 behavior of all Ada 95 compilers, and the GNAT compiler conforms to
5073 In addition, there are sections throughout the Ada 95
5074 reference manual headed
5075 by the phrase ``implementation advice''. These sections are not normative,
5076 i.e.@: they do not specify requirements that all compilers must
5077 follow. Rather they provide advice on generally desirable behavior. You
5078 may wonder why they are not requirements. The most typical answer is
5079 that they describe behavior that seems generally desirable, but cannot
5080 be provided on all systems, or which may be undesirable on some systems.
5082 As far as practical, GNAT follows the implementation advice sections in
5083 the Ada 95 Reference Manual. This chapter contains a table giving the
5084 reference manual section number, paragraph number and several keywords
5085 for each advice. Each entry consists of the text of the advice followed
5086 by the GNAT interpretation of this advice. Most often, this simply says
5087 ``followed'', which means that GNAT follows the advice. However, in a
5088 number of cases, GNAT deliberately deviates from this advice, in which
5089 case the text describes what GNAT does and why.
5091 @cindex Error detection
5092 @unnumberedsec 1.1.3(20): Error Detection
5095 If an implementation detects the use of an unsupported Specialized Needs
5096 Annex feature at run time, it should raise @code{Program_Error} if
5099 Not relevant. All specialized needs annex features are either supported,
5100 or diagnosed at compile time.
5103 @unnumberedsec 1.1.3(31): Child Units
5106 If an implementation wishes to provide implementation-defined
5107 extensions to the functionality of a language-defined library unit, it
5108 should normally do so by adding children to the library unit.
5112 @cindex Bounded errors
5113 @unnumberedsec 1.1.5(12): Bounded Errors
5116 If an implementation detects a bounded error or erroneous
5117 execution, it should raise @code{Program_Error}.
5119 Followed in all cases in which the implementation detects a bounded
5120 error or erroneous execution. Not all such situations are detected at
5124 @unnumberedsec 2.8(16): Pragmas
5127 Normally, implementation-defined pragmas should have no semantic effect
5128 for error-free programs; that is, if the implementation-defined pragmas
5129 are removed from a working program, the program should still be legal,
5130 and should still have the same semantics.
5132 The following implementation defined pragmas are exceptions to this
5144 @item CPP_Constructor
5152 @item Interface_Name
5154 @item Machine_Attribute
5156 @item Unimplemented_Unit
5158 @item Unchecked_Union
5163 In each of the above cases, it is essential to the purpose of the pragma
5164 that this advice not be followed. For details see the separate section
5165 on implementation defined pragmas.
5167 @unnumberedsec 2.8(17-19): Pragmas
5170 Normally, an implementation should not define pragmas that can
5171 make an illegal program legal, except as follows:
5175 A pragma used to complete a declaration, such as a pragma @code{Import};
5179 A pragma used to configure the environment by adding, removing, or
5180 replacing @code{library_items}.
5182 See response to paragraph 16 of this same section.
5184 @cindex Character Sets
5185 @cindex Alternative Character Sets
5186 @unnumberedsec 3.5.2(5): Alternative Character Sets
5189 If an implementation supports a mode with alternative interpretations
5190 for @code{Character} and @code{Wide_Character}, the set of graphic
5191 characters of @code{Character} should nevertheless remain a proper
5192 subset of the set of graphic characters of @code{Wide_Character}. Any
5193 character set ``localizations'' should be reflected in the results of
5194 the subprograms defined in the language-defined package
5195 @code{Characters.Handling} (see A.3) available in such a mode. In a mode with
5196 an alternative interpretation of @code{Character}, the implementation should
5197 also support a corresponding change in what is a legal
5198 @code{identifier_letter}.
5200 Not all wide character modes follow this advice, in particular the JIS
5201 and IEC modes reflect standard usage in Japan, and in these encoding,
5202 the upper half of the Latin-1 set is not part of the wide-character
5203 subset, since the most significant bit is used for wide character
5204 encoding. However, this only applies to the external forms. Internally
5205 there is no such restriction.
5207 @cindex Integer types
5208 @unnumberedsec 3.5.4(28): Integer Types
5212 An implementation should support @code{Long_Integer} in addition to
5213 @code{Integer} if the target machine supports 32-bit (or longer)
5214 arithmetic. No other named integer subtypes are recommended for package
5215 @code{Standard}. Instead, appropriate named integer subtypes should be
5216 provided in the library package @code{Interfaces} (see B.2).
5218 @code{Long_Integer} is supported. Other standard integer types are supported
5219 so this advice is not fully followed. These types
5220 are supported for convenient interface to C, and so that all hardware
5221 types of the machine are easily available.
5222 @unnumberedsec 3.5.4(29): Integer Types
5226 An implementation for a two's complement machine should support
5227 modular types with a binary modulus up to @code{System.Max_Int*2+2}. An
5228 implementation should support a non-binary modules up to @code{Integer'Last}.
5232 @cindex Enumeration values
5233 @unnumberedsec 3.5.5(8): Enumeration Values
5236 For the evaluation of a call on @code{@var{S}'Pos} for an enumeration
5237 subtype, if the value of the operand does not correspond to the internal
5238 code for any enumeration literal of its type (perhaps due to an
5239 un-initialized variable), then the implementation should raise
5240 @code{Program_Error}. This is particularly important for enumeration
5241 types with noncontiguous internal codes specified by an
5242 enumeration_representation_clause.
5247 @unnumberedsec 3.5.7(17): Float Types
5250 An implementation should support @code{Long_Float} in addition to
5251 @code{Float} if the target machine supports 11 or more digits of
5252 precision. No other named floating point subtypes are recommended for
5253 package @code{Standard}. Instead, appropriate named floating point subtypes
5254 should be provided in the library package @code{Interfaces} (see B.2).
5256 @code{Short_Float} and @code{Long_Long_Float} are also provided. The
5257 former provides improved compatibility with other implementations
5258 supporting this type. The latter corresponds to the highest precision
5259 floating-point type supported by the hardware. On most machines, this
5260 will be the same as @code{Long_Float}, but on some machines, it will
5261 correspond to the IEEE extended form. The notable case is all ia32
5262 (x86) implementations, where @code{Long_Long_Float} corresponds to
5263 the 80-bit extended precision format supported in hardware on this
5264 processor. Note that the 128-bit format on SPARC is not supported,
5265 since this is a software rather than a hardware format.
5267 @cindex Multidimensional arrays
5268 @cindex Arrays, multidimensional
5269 @unnumberedsec 3.6.2(11): Multidimensional Arrays
5272 An implementation should normally represent multidimensional arrays in
5273 row-major order, consistent with the notation used for multidimensional
5274 array aggregates (see 4.3.3). However, if a pragma @code{Convention}
5275 (@code{Fortran}, @dots{}) applies to a multidimensional array type, then
5276 column-major order should be used instead (see B.5, ``Interfacing with
5281 @findex Duration'Small
5282 @unnumberedsec 9.6(30-31): Duration'Small
5285 Whenever possible in an implementation, the value of @code{Duration'Small}
5286 should be no greater than 100 microseconds.
5288 Followed. (@code{Duration'Small} = 10**(@minus{}9)).
5292 The time base for @code{delay_relative_statements} should be monotonic;
5293 it need not be the same time base as used for @code{Calendar.Clock}.
5297 @unnumberedsec 10.2.1(12): Consistent Representation
5300 In an implementation, a type declared in a pre-elaborated package should
5301 have the same representation in every elaboration of a given version of
5302 the package, whether the elaborations occur in distinct executions of
5303 the same program, or in executions of distinct programs or partitions
5304 that include the given version.
5306 Followed, except in the case of tagged types. Tagged types involve
5307 implicit pointers to a local copy of a dispatch table, and these pointers
5308 have representations which thus depend on a particular elaboration of the
5309 package. It is not easy to see how it would be possible to follow this
5310 advice without severely impacting efficiency of execution.
5312 @cindex Exception information
5313 @unnumberedsec 11.4.1(19): Exception Information
5316 @code{Exception_Message} by default and @code{Exception_Information}
5317 should produce information useful for
5318 debugging. @code{Exception_Message} should be short, about one
5319 line. @code{Exception_Information} can be long. @code{Exception_Message}
5320 should not include the
5321 @code{Exception_Name}. @code{Exception_Information} should include both
5322 the @code{Exception_Name} and the @code{Exception_Message}.
5324 Followed. For each exception that doesn't have a specified
5325 @code{Exception_Message}, the compiler generates one containing the location
5326 of the raise statement. This location has the form ``file:line'', where
5327 file is the short file name (without path information) and line is the line
5328 number in the file. Note that in the case of the Zero Cost Exception
5329 mechanism, these messages become redundant with the Exception_Information that
5330 contains a full backtrace of the calling sequence, so they are disabled.
5331 To disable explicitly the generation of the source location message, use the
5332 Pragma @code{Discard_Names}.
5334 @cindex Suppression of checks
5335 @cindex Checks, suppression of
5336 @unnumberedsec 11.5(28): Suppression of Checks
5339 The implementation should minimize the code executed for checks that
5340 have been suppressed.
5344 @cindex Representation clauses
5345 @unnumberedsec 13.1 (21-24): Representation Clauses
5348 The recommended level of support for all representation items is
5349 qualified as follows:
5353 An implementation need not support representation items containing
5354 non-static expressions, except that an implementation should support a
5355 representation item for a given entity if each non-static expression in
5356 the representation item is a name that statically denotes a constant
5357 declared before the entity.
5359 Followed. In fact, GNAT goes beyond the recommended level of support
5360 by allowing nonstatic expressions in some representation clauses even
5361 without the need to declare constants initialized with the values of
5365 @smallexample @c ada
5368 for Y'Address use X'Address;>>
5374 An implementation need not support a specification for the @code{Size}
5375 for a given composite subtype, nor the size or storage place for an
5376 object (including a component) of a given composite subtype, unless the
5377 constraints on the subtype and its composite subcomponents (if any) are
5378 all static constraints.
5380 Followed. Size Clauses are not permitted on non-static components, as
5385 An aliased component, or a component whose type is by-reference, should
5386 always be allocated at an addressable location.
5390 @cindex Packed types
5391 @unnumberedsec 13.2(6-8): Packed Types
5394 If a type is packed, then the implementation should try to minimize
5395 storage allocated to objects of the type, possibly at the expense of
5396 speed of accessing components, subject to reasonable complexity in
5397 addressing calculations.
5401 The recommended level of support pragma @code{Pack} is:
5403 For a packed record type, the components should be packed as tightly as
5404 possible subject to the Sizes of the component subtypes, and subject to
5405 any @code{record_representation_clause} that applies to the type; the
5406 implementation may, but need not, reorder components or cross aligned
5407 word boundaries to improve the packing. A component whose @code{Size} is
5408 greater than the word size may be allocated an integral number of words.
5410 Followed. Tight packing of arrays is supported for all component sizes
5411 up to 64-bits. If the array component size is 1 (that is to say, if
5412 the component is a boolean type or an enumeration type with two values)
5413 then values of the type are implicitly initialized to zero. This
5414 happens both for objects of the packed type, and for objects that have a
5415 subcomponent of the packed type.
5419 An implementation should support Address clauses for imported
5423 @cindex @code{Address} clauses
5424 @unnumberedsec 13.3(14-19): Address Clauses
5428 For an array @var{X}, @code{@var{X}'Address} should point at the first
5429 component of the array, and not at the array bounds.
5435 The recommended level of support for the @code{Address} attribute is:
5437 @code{@var{X}'Address} should produce a useful result if @var{X} is an
5438 object that is aliased or of a by-reference type, or is an entity whose
5439 @code{Address} has been specified.
5441 Followed. A valid address will be produced even if none of those
5442 conditions have been met. If necessary, the object is forced into
5443 memory to ensure the address is valid.
5447 An implementation should support @code{Address} clauses for imported
5454 Objects (including subcomponents) that are aliased or of a by-reference
5455 type should be allocated on storage element boundaries.
5461 If the @code{Address} of an object is specified, or it is imported or exported,
5462 then the implementation should not perform optimizations based on
5463 assumptions of no aliases.
5467 @cindex @code{Alignment} clauses
5468 @unnumberedsec 13.3(29-35): Alignment Clauses
5471 The recommended level of support for the @code{Alignment} attribute for
5474 An implementation should support specified Alignments that are factors
5475 and multiples of the number of storage elements per word, subject to the
5482 An implementation need not support specified @code{Alignment}s for
5483 combinations of @code{Size}s and @code{Alignment}s that cannot be easily
5484 loaded and stored by available machine instructions.
5490 An implementation need not support specified @code{Alignment}s that are
5491 greater than the maximum @code{Alignment} the implementation ever returns by
5498 The recommended level of support for the @code{Alignment} attribute for
5501 Same as above, for subtypes, but in addition:
5507 For stand-alone library-level objects of statically constrained
5508 subtypes, the implementation should support all @code{Alignment}s
5509 supported by the target linker. For example, page alignment is likely to
5510 be supported for such objects, but not for subtypes.
5514 @cindex @code{Size} clauses
5515 @unnumberedsec 13.3(42-43): Size Clauses
5518 The recommended level of support for the @code{Size} attribute of
5521 A @code{Size} clause should be supported for an object if the specified
5522 @code{Size} is at least as large as its subtype's @code{Size}, and
5523 corresponds to a size in storage elements that is a multiple of the
5524 object's @code{Alignment} (if the @code{Alignment} is nonzero).
5528 @unnumberedsec 13.3(50-56): Size Clauses
5531 If the @code{Size} of a subtype is specified, and allows for efficient
5532 independent addressability (see 9.10) on the target architecture, then
5533 the @code{Size} of the following objects of the subtype should equal the
5534 @code{Size} of the subtype:
5536 Aliased objects (including components).
5542 @code{Size} clause on a composite subtype should not affect the
5543 internal layout of components.
5549 The recommended level of support for the @code{Size} attribute of subtypes is:
5553 The @code{Size} (if not specified) of a static discrete or fixed point
5554 subtype should be the number of bits needed to represent each value
5555 belonging to the subtype using an unbiased representation, leaving space
5556 for a sign bit only if the subtype contains negative values. If such a
5557 subtype is a first subtype, then an implementation should support a
5558 specified @code{Size} for it that reflects this representation.
5564 For a subtype implemented with levels of indirection, the @code{Size}
5565 should include the size of the pointers, but not the size of what they
5570 @cindex @code{Component_Size} clauses
5571 @unnumberedsec 13.3(71-73): Component Size Clauses
5574 The recommended level of support for the @code{Component_Size}
5579 An implementation need not support specified @code{Component_Sizes} that are
5580 less than the @code{Size} of the component subtype.
5586 An implementation should support specified @code{Component_Size}s that
5587 are factors and multiples of the word size. For such
5588 @code{Component_Size}s, the array should contain no gaps between
5589 components. For other @code{Component_Size}s (if supported), the array
5590 should contain no gaps between components when packing is also
5591 specified; the implementation should forbid this combination in cases
5592 where it cannot support a no-gaps representation.
5596 @cindex Enumeration representation clauses
5597 @cindex Representation clauses, enumeration
5598 @unnumberedsec 13.4(9-10): Enumeration Representation Clauses
5601 The recommended level of support for enumeration representation clauses
5604 An implementation need not support enumeration representation clauses
5605 for boolean types, but should at minimum support the internal codes in
5606 the range @code{System.Min_Int.System.Max_Int}.
5610 @cindex Record representation clauses
5611 @cindex Representation clauses, records
5612 @unnumberedsec 13.5.1(17-22): Record Representation Clauses
5615 The recommended level of support for
5616 @*@code{record_representation_clauses} is:
5618 An implementation should support storage places that can be extracted
5619 with a load, mask, shift sequence of machine code, and set with a load,
5620 shift, mask, store sequence, given the available machine instructions
5627 A storage place should be supported if its size is equal to the
5628 @code{Size} of the component subtype, and it starts and ends on a
5629 boundary that obeys the @code{Alignment} of the component subtype.
5635 If the default bit ordering applies to the declaration of a given type,
5636 then for a component whose subtype's @code{Size} is less than the word
5637 size, any storage place that does not cross an aligned word boundary
5638 should be supported.
5644 An implementation may reserve a storage place for the tag field of a
5645 tagged type, and disallow other components from overlapping that place.
5647 Followed. The storage place for the tag field is the beginning of the tagged
5648 record, and its size is Address'Size. GNAT will reject an explicit component
5649 clause for the tag field.
5653 An implementation need not support a @code{component_clause} for a
5654 component of an extension part if the storage place is not after the
5655 storage places of all components of the parent type, whether or not
5656 those storage places had been specified.
5658 Followed. The above advice on record representation clauses is followed,
5659 and all mentioned features are implemented.
5661 @cindex Storage place attributes
5662 @unnumberedsec 13.5.2(5): Storage Place Attributes
5665 If a component is represented using some form of pointer (such as an
5666 offset) to the actual data of the component, and this data is contiguous
5667 with the rest of the object, then the storage place attributes should
5668 reflect the place of the actual data, not the pointer. If a component is
5669 allocated discontinuously from the rest of the object, then a warning
5670 should be generated upon reference to one of its storage place
5673 Followed. There are no such components in GNAT@.
5675 @cindex Bit ordering
5676 @unnumberedsec 13.5.3(7-8): Bit Ordering
5679 The recommended level of support for the non-default bit ordering is:
5683 If @code{Word_Size} = @code{Storage_Unit}, then the implementation
5684 should support the non-default bit ordering in addition to the default
5687 Followed. Word size does not equal storage size in this implementation.
5688 Thus non-default bit ordering is not supported.
5690 @cindex @code{Address}, as private type
5691 @unnumberedsec 13.7(37): Address as Private
5694 @code{Address} should be of a private type.
5698 @cindex Operations, on @code{Address}
5699 @cindex @code{Address}, operations of
5700 @unnumberedsec 13.7.1(16): Address Operations
5703 Operations in @code{System} and its children should reflect the target
5704 environment semantics as closely as is reasonable. For example, on most
5705 machines, it makes sense for address arithmetic to ``wrap around''.
5706 Operations that do not make sense should raise @code{Program_Error}.
5708 Followed. Address arithmetic is modular arithmetic that wraps around. No
5709 operation raises @code{Program_Error}, since all operations make sense.
5711 @cindex Unchecked conversion
5712 @unnumberedsec 13.9(14-17): Unchecked Conversion
5715 The @code{Size} of an array object should not include its bounds; hence,
5716 the bounds should not be part of the converted data.
5722 The implementation should not generate unnecessary run-time checks to
5723 ensure that the representation of @var{S} is a representation of the
5724 target type. It should take advantage of the permission to return by
5725 reference when possible. Restrictions on unchecked conversions should be
5726 avoided unless required by the target environment.
5728 Followed. There are no restrictions on unchecked conversion. A warning is
5729 generated if the source and target types do not have the same size since
5730 the semantics in this case may be target dependent.
5734 The recommended level of support for unchecked conversions is:
5738 Unchecked conversions should be supported and should be reversible in
5739 the cases where this clause defines the result. To enable meaningful use
5740 of unchecked conversion, a contiguous representation should be used for
5741 elementary subtypes, for statically constrained array subtypes whose
5742 component subtype is one of the subtypes described in this paragraph,
5743 and for record subtypes without discriminants whose component subtypes
5744 are described in this paragraph.
5748 @cindex Heap usage, implicit
5749 @unnumberedsec 13.11(23-25): Implicit Heap Usage
5752 An implementation should document any cases in which it dynamically
5753 allocates heap storage for a purpose other than the evaluation of an
5756 Followed, the only other points at which heap storage is dynamically
5757 allocated are as follows:
5761 At initial elaboration time, to allocate dynamically sized global
5765 To allocate space for a task when a task is created.
5768 To extend the secondary stack dynamically when needed. The secondary
5769 stack is used for returning variable length results.
5774 A default (implementation-provided) storage pool for an
5775 access-to-constant type should not have overhead to support deallocation of
5782 A storage pool for an anonymous access type should be created at the
5783 point of an allocator for the type, and be reclaimed when the designated
5784 object becomes inaccessible.
5788 @cindex Unchecked deallocation
5789 @unnumberedsec 13.11.2(17): Unchecked De-allocation
5792 For a standard storage pool, @code{Free} should actually reclaim the
5797 @cindex Stream oriented attributes
5798 @unnumberedsec 13.13.2(17): Stream Oriented Attributes
5801 If a stream element is the same size as a storage element, then the
5802 normal in-memory representation should be used by @code{Read} and
5803 @code{Write} for scalar objects. Otherwise, @code{Read} and @code{Write}
5804 should use the smallest number of stream elements needed to represent
5805 all values in the base range of the scalar type.
5808 Followed. By default, GNAT uses the interpretation suggested by AI-195,
5809 which specifies using the size of the first subtype.
5810 However, such an implementation is based on direct binary
5811 representations and is therefore target- and endianness-dependent.
5812 To address this issue, GNAT also supplies an alternate implementation
5813 of the stream attributes @code{Read} and @code{Write},
5814 which uses the target-independent XDR standard representation
5816 @cindex XDR representation
5817 @cindex @code{Read} attribute
5818 @cindex @code{Write} attribute
5819 @cindex Stream oriented attributes
5820 The XDR implementation is provided as an alternative body of the
5821 @code{System.Stream_Attributes} package, in the file
5822 @file{s-strxdr.adb} in the GNAT library.
5823 There is no @file{s-strxdr.ads} file.
5824 In order to install the XDR implementation, do the following:
5826 @item Replace the default implementation of the
5827 @code{System.Stream_Attributes} package with the XDR implementation.
5828 For example on a Unix platform issue the commands:
5830 $ mv s-stratt.adb s-strold.adb
5831 $ mv s-strxdr.adb s-stratt.adb
5835 Rebuild the GNAT run-time library as documented in the
5836 @cite{GNAT User's Guide}
5839 @unnumberedsec A.1(52): Names of Predefined Numeric Types
5842 If an implementation provides additional named predefined integer types,
5843 then the names should end with @samp{Integer} as in
5844 @samp{Long_Integer}. If an implementation provides additional named
5845 predefined floating point types, then the names should end with
5846 @samp{Float} as in @samp{Long_Float}.
5850 @findex Ada.Characters.Handling
5851 @unnumberedsec A.3.2(49): @code{Ada.Characters.Handling}
5854 If an implementation provides a localized definition of @code{Character}
5855 or @code{Wide_Character}, then the effects of the subprograms in
5856 @code{Characters.Handling} should reflect the localizations. See also
5859 Followed. GNAT provides no such localized definitions.
5861 @cindex Bounded-length strings
5862 @unnumberedsec A.4.4(106): Bounded-Length String Handling
5865 Bounded string objects should not be implemented by implicit pointers
5866 and dynamic allocation.
5868 Followed. No implicit pointers or dynamic allocation are used.
5870 @cindex Random number generation
5871 @unnumberedsec A.5.2(46-47): Random Number Generation
5874 Any storage associated with an object of type @code{Generator} should be
5875 reclaimed on exit from the scope of the object.
5881 If the generator period is sufficiently long in relation to the number
5882 of distinct initiator values, then each possible value of
5883 @code{Initiator} passed to @code{Reset} should initiate a sequence of
5884 random numbers that does not, in a practical sense, overlap the sequence
5885 initiated by any other value. If this is not possible, then the mapping
5886 between initiator values and generator states should be a rapidly
5887 varying function of the initiator value.
5889 Followed. The generator period is sufficiently long for the first
5890 condition here to hold true.
5892 @findex Get_Immediate
5893 @unnumberedsec A.10.7(23): @code{Get_Immediate}
5896 The @code{Get_Immediate} procedures should be implemented with
5897 unbuffered input. For a device such as a keyboard, input should be
5898 @dfn{available} if a key has already been typed, whereas for a disk
5899 file, input should always be available except at end of file. For a file
5900 associated with a keyboard-like device, any line-editing features of the
5901 underlying operating system should be disabled during the execution of
5902 @code{Get_Immediate}.
5904 Followed on all targets except VxWorks. For VxWorks, there is no way to
5905 provide this functionality that does not result in the input buffer being
5906 flushed before the @code{Get_Immediate} call. A special unit
5907 @code{Interfaces.Vxworks.IO} is provided that contains routines to enable
5911 @unnumberedsec B.1(39-41): Pragma @code{Export}
5914 If an implementation supports pragma @code{Export} to a given language,
5915 then it should also allow the main subprogram to be written in that
5916 language. It should support some mechanism for invoking the elaboration
5917 of the Ada library units included in the system, and for invoking the
5918 finalization of the environment task. On typical systems, the
5919 recommended mechanism is to provide two subprograms whose link names are
5920 @code{adainit} and @code{adafinal}. @code{adainit} should contain the
5921 elaboration code for library units. @code{adafinal} should contain the
5922 finalization code. These subprograms should have no effect the second
5923 and subsequent time they are called.
5929 Automatic elaboration of pre-elaborated packages should be
5930 provided when pragma @code{Export} is supported.
5932 Followed when the main program is in Ada. If the main program is in a
5933 foreign language, then
5934 @code{adainit} must be called to elaborate pre-elaborated
5939 For each supported convention @var{L} other than @code{Intrinsic}, an
5940 implementation should support @code{Import} and @code{Export} pragmas
5941 for objects of @var{L}-compatible types and for subprograms, and pragma
5942 @code{Convention} for @var{L}-eligible types and for subprograms,
5943 presuming the other language has corresponding features. Pragma
5944 @code{Convention} need not be supported for scalar types.
5948 @cindex Package @code{Interfaces}
5950 @unnumberedsec B.2(12-13): Package @code{Interfaces}
5953 For each implementation-defined convention identifier, there should be a
5954 child package of package Interfaces with the corresponding name. This
5955 package should contain any declarations that would be useful for
5956 interfacing to the language (implementation) represented by the
5957 convention. Any declarations useful for interfacing to any language on
5958 the given hardware architecture should be provided directly in
5961 Followed. An additional package not defined
5962 in the Ada 95 Reference Manual is @code{Interfaces.CPP}, used
5963 for interfacing to C++.
5967 An implementation supporting an interface to C, COBOL, or Fortran should
5968 provide the corresponding package or packages described in the following
5971 Followed. GNAT provides all the packages described in this section.
5973 @cindex C, interfacing with
5974 @unnumberedsec B.3(63-71): Interfacing with C
5977 An implementation should support the following interface correspondences
5984 An Ada procedure corresponds to a void-returning C function.
5990 An Ada function corresponds to a non-void C function.
5996 An Ada @code{in} scalar parameter is passed as a scalar argument to a C
6003 An Ada @code{in} parameter of an access-to-object type with designated
6004 type @var{T} is passed as a @code{@var{t}*} argument to a C function,
6005 where @var{t} is the C type corresponding to the Ada type @var{T}.
6011 An Ada access @var{T} parameter, or an Ada @code{out} or @code{in out}
6012 parameter of an elementary type @var{T}, is passed as a @code{@var{t}*}
6013 argument to a C function, where @var{t} is the C type corresponding to
6014 the Ada type @var{T}. In the case of an elementary @code{out} or
6015 @code{in out} parameter, a pointer to a temporary copy is used to
6016 preserve by-copy semantics.
6022 An Ada parameter of a record type @var{T}, of any mode, is passed as a
6023 @code{@var{t}*} argument to a C function, where @var{t} is the C
6024 structure corresponding to the Ada type @var{T}.
6026 Followed. This convention may be overridden by the use of the C_Pass_By_Copy
6027 pragma, or Convention, or by explicitly specifying the mechanism for a given
6028 call using an extended import or export pragma.
6032 An Ada parameter of an array type with component type @var{T}, of any
6033 mode, is passed as a @code{@var{t}*} argument to a C function, where
6034 @var{t} is the C type corresponding to the Ada type @var{T}.
6040 An Ada parameter of an access-to-subprogram type is passed as a pointer
6041 to a C function whose prototype corresponds to the designated
6042 subprogram's specification.
6046 @cindex COBOL, interfacing with
6047 @unnumberedsec B.4(95-98): Interfacing with COBOL
6050 An Ada implementation should support the following interface
6051 correspondences between Ada and COBOL@.
6057 An Ada access @var{T} parameter is passed as a @samp{BY REFERENCE} data item of
6058 the COBOL type corresponding to @var{T}.
6064 An Ada in scalar parameter is passed as a @samp{BY CONTENT} data item of
6065 the corresponding COBOL type.
6071 Any other Ada parameter is passed as a @samp{BY REFERENCE} data item of the
6072 COBOL type corresponding to the Ada parameter type; for scalars, a local
6073 copy is used if necessary to ensure by-copy semantics.
6077 @cindex Fortran, interfacing with
6078 @unnumberedsec B.5(22-26): Interfacing with Fortran
6081 An Ada implementation should support the following interface
6082 correspondences between Ada and Fortran:
6088 An Ada procedure corresponds to a Fortran subroutine.
6094 An Ada function corresponds to a Fortran function.
6100 An Ada parameter of an elementary, array, or record type @var{T} is
6101 passed as a @var{T} argument to a Fortran procedure, where @var{T} is
6102 the Fortran type corresponding to the Ada type @var{T}, and where the
6103 INTENT attribute of the corresponding dummy argument matches the Ada
6104 formal parameter mode; the Fortran implementation's parameter passing
6105 conventions are used. For elementary types, a local copy is used if
6106 necessary to ensure by-copy semantics.
6112 An Ada parameter of an access-to-subprogram type is passed as a
6113 reference to a Fortran procedure whose interface corresponds to the
6114 designated subprogram's specification.
6118 @cindex Machine operations
6119 @unnumberedsec C.1(3-5): Access to Machine Operations
6122 The machine code or intrinsic support should allow access to all
6123 operations normally available to assembly language programmers for the
6124 target environment, including privileged instructions, if any.
6130 The interfacing pragmas (see Annex B) should support interface to
6131 assembler; the default assembler should be associated with the
6132 convention identifier @code{Assembler}.
6138 If an entity is exported to assembly language, then the implementation
6139 should allocate it at an addressable location, and should ensure that it
6140 is retained by the linking process, even if not otherwise referenced
6141 from the Ada code. The implementation should assume that any call to a
6142 machine code or assembler subprogram is allowed to read or update every
6143 object that is specified as exported.
6147 @unnumberedsec C.1(10-16): Access to Machine Operations
6150 The implementation should ensure that little or no overhead is
6151 associated with calling intrinsic and machine-code subprograms.
6153 Followed for both intrinsics and machine-code subprograms.
6157 It is recommended that intrinsic subprograms be provided for convenient
6158 access to any machine operations that provide special capabilities or
6159 efficiency and that are not otherwise available through the language
6162 Followed. A full set of machine operation intrinsic subprograms is provided.
6166 Atomic read-modify-write operations---e.g.@:, test and set, compare and
6167 swap, decrement and test, enqueue/dequeue.
6169 Followed on any target supporting such operations.
6173 Standard numeric functions---e.g.@:, sin, log.
6175 Followed on any target supporting such operations.
6179 String manipulation operations---e.g.@:, translate and test.
6181 Followed on any target supporting such operations.
6185 Vector operations---e.g.@:, compare vector against thresholds.
6187 Followed on any target supporting such operations.
6191 Direct operations on I/O ports.
6193 Followed on any target supporting such operations.
6195 @cindex Interrupt support
6196 @unnumberedsec C.3(28): Interrupt Support
6199 If the @code{Ceiling_Locking} policy is not in effect, the
6200 implementation should provide means for the application to specify which
6201 interrupts are to be blocked during protected actions, if the underlying
6202 system allows for a finer-grain control of interrupt blocking.
6204 Followed. The underlying system does not allow for finer-grain control
6205 of interrupt blocking.
6207 @cindex Protected procedure handlers
6208 @unnumberedsec C.3.1(20-21): Protected Procedure Handlers
6211 Whenever possible, the implementation should allow interrupt handlers to
6212 be called directly by the hardware.
6216 This is never possible under IRIX, so this is followed by default.
6218 Followed on any target where the underlying operating system permits
6223 Whenever practical, violations of any
6224 implementation-defined restrictions should be detected before run time.
6226 Followed. Compile time warnings are given when possible.
6228 @cindex Package @code{Interrupts}
6230 @unnumberedsec C.3.2(25): Package @code{Interrupts}
6234 If implementation-defined forms of interrupt handler procedures are
6235 supported, such as protected procedures with parameters, then for each
6236 such form of a handler, a type analogous to @code{Parameterless_Handler}
6237 should be specified in a child package of @code{Interrupts}, with the
6238 same operations as in the predefined package Interrupts.
6242 @cindex Pre-elaboration requirements
6243 @unnumberedsec C.4(14): Pre-elaboration Requirements
6246 It is recommended that pre-elaborated packages be implemented in such a
6247 way that there should be little or no code executed at run time for the
6248 elaboration of entities not already covered by the Implementation
6251 Followed. Executable code is generated in some cases, e.g.@: loops
6252 to initialize large arrays.
6254 @unnumberedsec C.5(8): Pragma @code{Discard_Names}
6258 If the pragma applies to an entity, then the implementation should
6259 reduce the amount of storage used for storing names associated with that
6264 @cindex Package @code{Task_Attributes}
6265 @findex Task_Attributes
6266 @unnumberedsec C.7.2(30): The Package Task_Attributes
6269 Some implementations are targeted to domains in which memory use at run
6270 time must be completely deterministic. For such implementations, it is
6271 recommended that the storage for task attributes will be pre-allocated
6272 statically and not from the heap. This can be accomplished by either
6273 placing restrictions on the number and the size of the task's
6274 attributes, or by using the pre-allocated storage for the first @var{N}
6275 attribute objects, and the heap for the others. In the latter case,
6276 @var{N} should be documented.
6278 Not followed. This implementation is not targeted to such a domain.
6280 @cindex Locking Policies
6281 @unnumberedsec D.3(17): Locking Policies
6285 The implementation should use names that end with @samp{_Locking} for
6286 locking policies defined by the implementation.
6288 Followed. A single implementation-defined locking policy is defined,
6289 whose name (@code{Inheritance_Locking}) follows this suggestion.
6291 @cindex Entry queuing policies
6292 @unnumberedsec D.4(16): Entry Queuing Policies
6295 Names that end with @samp{_Queuing} should be used
6296 for all implementation-defined queuing policies.
6298 Followed. No such implementation-defined queuing policies exist.
6300 @cindex Preemptive abort
6301 @unnumberedsec D.6(9-10): Preemptive Abort
6304 Even though the @code{abort_statement} is included in the list of
6305 potentially blocking operations (see 9.5.1), it is recommended that this
6306 statement be implemented in a way that never requires the task executing
6307 the @code{abort_statement} to block.
6313 On a multi-processor, the delay associated with aborting a task on
6314 another processor should be bounded; the implementation should use
6315 periodic polling, if necessary, to achieve this.
6319 @cindex Tasking restrictions
6320 @unnumberedsec D.7(21): Tasking Restrictions
6323 When feasible, the implementation should take advantage of the specified
6324 restrictions to produce a more efficient implementation.
6326 GNAT currently takes advantage of these restrictions by providing an optimized
6327 run time when the Ravenscar profile and the GNAT restricted run time set
6328 of restrictions are specified. See pragma @code{Profile (Ravenscar)} and
6329 pragma @code{Profile (Restricted)} for more details.
6331 @cindex Time, monotonic
6332 @unnumberedsec D.8(47-49): Monotonic Time
6335 When appropriate, implementations should provide configuration
6336 mechanisms to change the value of @code{Tick}.
6338 Such configuration mechanisms are not appropriate to this implementation
6339 and are thus not supported.
6343 It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock}
6344 be implemented as transformations of the same time base.
6350 It is recommended that the @dfn{best} time base which exists in
6351 the underlying system be available to the application through
6352 @code{Clock}. @dfn{Best} may mean highest accuracy or largest range.
6356 @cindex Partition communication subsystem
6358 @unnumberedsec E.5(28-29): Partition Communication Subsystem
6361 Whenever possible, the PCS on the called partition should allow for
6362 multiple tasks to call the RPC-receiver with different messages and
6363 should allow them to block until the corresponding subprogram body
6366 Followed by GLADE, a separately supplied PCS that can be used with
6371 The @code{Write} operation on a stream of type @code{Params_Stream_Type}
6372 should raise @code{Storage_Error} if it runs out of space trying to
6373 write the @code{Item} into the stream.
6375 Followed by GLADE, a separately supplied PCS that can be used with
6378 @cindex COBOL support
6379 @unnumberedsec F(7): COBOL Support
6382 If COBOL (respectively, C) is widely supported in the target
6383 environment, implementations supporting the Information Systems Annex
6384 should provide the child package @code{Interfaces.COBOL} (respectively,
6385 @code{Interfaces.C}) specified in Annex B and should support a
6386 @code{convention_identifier} of COBOL (respectively, C) in the interfacing
6387 pragmas (see Annex B), thus allowing Ada programs to interface with
6388 programs written in that language.
6392 @cindex Decimal radix support
6393 @unnumberedsec F.1(2): Decimal Radix Support
6396 Packed decimal should be used as the internal representation for objects
6397 of subtype @var{S} when @var{S}'Machine_Radix = 10.
6399 Not followed. GNAT ignores @var{S}'Machine_Radix and always uses binary
6403 @unnumberedsec G: Numerics
6406 If Fortran (respectively, C) is widely supported in the target
6407 environment, implementations supporting the Numerics Annex
6408 should provide the child package @code{Interfaces.Fortran} (respectively,
6409 @code{Interfaces.C}) specified in Annex B and should support a
6410 @code{convention_identifier} of Fortran (respectively, C) in the interfacing
6411 pragmas (see Annex B), thus allowing Ada programs to interface with
6412 programs written in that language.
6416 @cindex Complex types
6417 @unnumberedsec G.1.1(56-58): Complex Types
6420 Because the usual mathematical meaning of multiplication of a complex
6421 operand and a real operand is that of the scaling of both components of
6422 the former by the latter, an implementation should not perform this
6423 operation by first promoting the real operand to complex type and then
6424 performing a full complex multiplication. In systems that, in the
6425 future, support an Ada binding to IEC 559:1989, the latter technique
6426 will not generate the required result when one of the components of the
6427 complex operand is infinite. (Explicit multiplication of the infinite
6428 component by the zero component obtained during promotion yields a NaN
6429 that propagates into the final result.) Analogous advice applies in the
6430 case of multiplication of a complex operand and a pure-imaginary
6431 operand, and in the case of division of a complex operand by a real or
6432 pure-imaginary operand.
6438 Similarly, because the usual mathematical meaning of addition of a
6439 complex operand and a real operand is that the imaginary operand remains
6440 unchanged, an implementation should not perform this operation by first
6441 promoting the real operand to complex type and then performing a full
6442 complex addition. In implementations in which the @code{Signed_Zeros}
6443 attribute of the component type is @code{True} (and which therefore
6444 conform to IEC 559:1989 in regard to the handling of the sign of zero in
6445 predefined arithmetic operations), the latter technique will not
6446 generate the required result when the imaginary component of the complex
6447 operand is a negatively signed zero. (Explicit addition of the negative
6448 zero to the zero obtained during promotion yields a positive zero.)
6449 Analogous advice applies in the case of addition of a complex operand
6450 and a pure-imaginary operand, and in the case of subtraction of a
6451 complex operand and a real or pure-imaginary operand.
6457 Implementations in which @code{Real'Signed_Zeros} is @code{True} should
6458 attempt to provide a rational treatment of the signs of zero results and
6459 result components. As one example, the result of the @code{Argument}
6460 function should have the sign of the imaginary component of the
6461 parameter @code{X} when the point represented by that parameter lies on
6462 the positive real axis; as another, the sign of the imaginary component
6463 of the @code{Compose_From_Polar} function should be the same as
6464 (respectively, the opposite of) that of the @code{Argument} parameter when that
6465 parameter has a value of zero and the @code{Modulus} parameter has a
6466 nonnegative (respectively, negative) value.
6470 @cindex Complex elementary functions
6471 @unnumberedsec G.1.2(49): Complex Elementary Functions
6474 Implementations in which @code{Complex_Types.Real'Signed_Zeros} is
6475 @code{True} should attempt to provide a rational treatment of the signs
6476 of zero results and result components. For example, many of the complex
6477 elementary functions have components that are odd functions of one of
6478 the parameter components; in these cases, the result component should
6479 have the sign of the parameter component at the origin. Other complex
6480 elementary functions have zero components whose sign is opposite that of
6481 a parameter component at the origin, or is always positive or always
6486 @cindex Accuracy requirements
6487 @unnumberedsec G.2.4(19): Accuracy Requirements
6490 The versions of the forward trigonometric functions without a
6491 @code{Cycle} parameter should not be implemented by calling the
6492 corresponding version with a @code{Cycle} parameter of
6493 @code{2.0*Numerics.Pi}, since this will not provide the required
6494 accuracy in some portions of the domain. For the same reason, the
6495 version of @code{Log} without a @code{Base} parameter should not be
6496 implemented by calling the corresponding version with a @code{Base}
6497 parameter of @code{Numerics.e}.
6501 @cindex Complex arithmetic accuracy
6502 @cindex Accuracy, complex arithmetic
6503 @unnumberedsec G.2.6(15): Complex Arithmetic Accuracy
6507 The version of the @code{Compose_From_Polar} function without a
6508 @code{Cycle} parameter should not be implemented by calling the
6509 corresponding version with a @code{Cycle} parameter of
6510 @code{2.0*Numerics.Pi}, since this will not provide the required
6511 accuracy in some portions of the domain.
6515 @c -----------------------------------------
6516 @node Implementation Defined Characteristics
6517 @chapter Implementation Defined Characteristics
6520 In addition to the implementation dependent pragmas and attributes, and
6521 the implementation advice, there are a number of other features of Ada
6522 95 that are potentially implementation dependent. These are mentioned
6523 throughout the Ada 95 Reference Manual, and are summarized in annex M@.
6525 A requirement for conforming Ada compilers is that they provide
6526 documentation describing how the implementation deals with each of these
6527 issues. In this chapter, you will find each point in annex M listed
6528 followed by a description in italic font of how GNAT
6532 implementation on IRIX 5.3 operating system or greater
6534 handles the implementation dependence.
6536 You can use this chapter as a guide to minimizing implementation
6537 dependent features in your programs if portability to other compilers
6538 and other operating systems is an important consideration. The numbers
6539 in each section below correspond to the paragraph number in the Ada 95
6545 @strong{2}. Whether or not each recommendation given in Implementation
6546 Advice is followed. See 1.1.2(37).
6549 @xref{Implementation Advice}.
6554 @strong{3}. Capacity limitations of the implementation. See 1.1.3(3).
6557 The complexity of programs that can be processed is limited only by the
6558 total amount of available virtual memory, and disk space for the
6559 generated object files.
6564 @strong{4}. Variations from the standard that are impractical to avoid
6565 given the implementation's execution environment. See 1.1.3(6).
6568 There are no variations from the standard.
6573 @strong{5}. Which @code{code_statement}s cause external
6574 interactions. See 1.1.3(10).
6577 Any @code{code_statement} can potentially cause external interactions.
6582 @strong{6}. The coded representation for the text of an Ada
6583 program. See 2.1(4).
6586 See separate section on source representation.
6591 @strong{7}. The control functions allowed in comments. See 2.1(14).
6594 See separate section on source representation.
6599 @strong{8}. The representation for an end of line. See 2.2(2).
6602 See separate section on source representation.
6607 @strong{9}. Maximum supported line length and lexical element
6608 length. See 2.2(15).
6611 The maximum line length is 255 characters an the maximum length of a
6612 lexical element is also 255 characters.
6617 @strong{10}. Implementation defined pragmas. See 2.8(14).
6621 @xref{Implementation Defined Pragmas}.
6626 @strong{11}. Effect of pragma @code{Optimize}. See 2.8(27).
6629 Pragma @code{Optimize}, if given with a @code{Time} or @code{Space}
6630 parameter, checks that the optimization flag is set, and aborts if it is
6636 @strong{12}. The sequence of characters of the value returned by
6637 @code{@var{S}'Image} when some of the graphic characters of
6638 @code{@var{S}'Wide_Image} are not defined in @code{Character}. See
6642 The sequence of characters is as defined by the wide character encoding
6643 method used for the source. See section on source representation for
6649 @strong{13}. The predefined integer types declared in
6650 @code{Standard}. See 3.5.4(25).
6654 @item Short_Short_Integer
6657 (Short) 16 bit signed
6661 64 bit signed (Alpha OpenVMS only)
6662 32 bit signed (all other targets)
6663 @item Long_Long_Integer
6670 @strong{14}. Any nonstandard integer types and the operators defined
6671 for them. See 3.5.4(26).
6674 There are no nonstandard integer types.
6679 @strong{15}. Any nonstandard real types and the operators defined for
6683 There are no nonstandard real types.
6688 @strong{16}. What combinations of requested decimal precision and range
6689 are supported for floating point types. See 3.5.7(7).
6692 The precision and range is as defined by the IEEE standard.
6697 @strong{17}. The predefined floating point types declared in
6698 @code{Standard}. See 3.5.7(16).
6705 (Short) 32 bit IEEE short
6708 @item Long_Long_Float
6709 64 bit IEEE long (80 bit IEEE long on x86 processors)
6715 @strong{18}. The small of an ordinary fixed point type. See 3.5.9(8).
6718 @code{Fine_Delta} is 2**(@minus{}63)
6723 @strong{19}. What combinations of small, range, and digits are
6724 supported for fixed point types. See 3.5.9(10).
6727 Any combinations are permitted that do not result in a small less than
6728 @code{Fine_Delta} and do not result in a mantissa larger than 63 bits.
6729 If the mantissa is larger than 53 bits on machines where Long_Long_Float
6730 is 64 bits (true of all architectures except ia32), then the output from
6731 Text_IO is accurate to only 53 bits, rather than the full mantissa. This
6732 is because floating-point conversions are used to convert fixed point.
6737 @strong{20}. The result of @code{Tags.Expanded_Name} for types declared
6738 within an unnamed @code{block_statement}. See 3.9(10).
6741 Block numbers of the form @code{B@var{nnn}}, where @var{nnn} is a
6742 decimal integer are allocated.
6747 @strong{21}. Implementation-defined attributes. See 4.1.4(12).
6750 @xref{Implementation Defined Attributes}.
6755 @strong{22}. Any implementation-defined time types. See 9.6(6).
6758 There are no implementation-defined time types.
6763 @strong{23}. The time base associated with relative delays.
6766 See 9.6(20). The time base used is that provided by the C library
6767 function @code{gettimeofday}.
6772 @strong{24}. The time base of the type @code{Calendar.Time}. See
6776 The time base used is that provided by the C library function
6777 @code{gettimeofday}.
6782 @strong{25}. The time zone used for package @code{Calendar}
6783 operations. See 9.6(24).
6786 The time zone used by package @code{Calendar} is the current system time zone
6787 setting for local time, as accessed by the C library function
6793 @strong{26}. Any limit on @code{delay_until_statements} of
6794 @code{select_statements}. See 9.6(29).
6797 There are no such limits.
6802 @strong{27}. Whether or not two non overlapping parts of a composite
6803 object are independently addressable, in the case where packing, record
6804 layout, or @code{Component_Size} is specified for the object. See
6808 Separate components are independently addressable if they do not share
6809 overlapping storage units.
6814 @strong{28}. The representation for a compilation. See 10.1(2).
6817 A compilation is represented by a sequence of files presented to the
6818 compiler in a single invocation of the @code{gcc} command.
6823 @strong{29}. Any restrictions on compilations that contain multiple
6824 compilation_units. See 10.1(4).
6827 No single file can contain more than one compilation unit, but any
6828 sequence of files can be presented to the compiler as a single
6834 @strong{30}. The mechanisms for creating an environment and for adding
6835 and replacing compilation units. See 10.1.4(3).
6838 See separate section on compilation model.
6843 @strong{31}. The manner of explicitly assigning library units to a
6844 partition. See 10.2(2).
6847 If a unit contains an Ada main program, then the Ada units for the partition
6848 are determined by recursive application of the rules in the Ada Reference
6849 Manual section 10.2(2-6). In other words, the Ada units will be those that
6850 are needed by the main program, and then this definition of need is applied
6851 recursively to those units, and the partition contains the transitive
6852 closure determined by this relationship. In short, all the necessary units
6853 are included, with no need to explicitly specify the list. If additional
6854 units are required, e.g.@: by foreign language units, then all units must be
6855 mentioned in the context clause of one of the needed Ada units.
6857 If the partition contains no main program, or if the main program is in
6858 a language other than Ada, then GNAT
6859 provides the binder options @code{-z} and @code{-n} respectively, and in
6860 this case a list of units can be explicitly supplied to the binder for
6861 inclusion in the partition (all units needed by these units will also
6862 be included automatically). For full details on the use of these
6863 options, refer to the @cite{GNAT User's Guide} sections on Binding
6869 @strong{32}. The implementation-defined means, if any, of specifying
6870 which compilation units are needed by a given compilation unit. See
6874 The units needed by a given compilation unit are as defined in
6875 the Ada Reference Manual section 10.2(2-6). There are no
6876 implementation-defined pragmas or other implementation-defined
6877 means for specifying needed units.
6882 @strong{33}. The manner of designating the main subprogram of a
6883 partition. See 10.2(7).
6886 The main program is designated by providing the name of the
6887 corresponding @file{ALI} file as the input parameter to the binder.
6892 @strong{34}. The order of elaboration of @code{library_items}. See
6896 The first constraint on ordering is that it meets the requirements of
6897 chapter 10 of the Ada 95 Reference Manual. This still leaves some
6898 implementation dependent choices, which are resolved by first
6899 elaborating bodies as early as possible (i.e.@: in preference to specs
6900 where there is a choice), and second by evaluating the immediate with
6901 clauses of a unit to determine the probably best choice, and
6902 third by elaborating in alphabetical order of unit names
6903 where a choice still remains.
6908 @strong{35}. Parameter passing and function return for the main
6909 subprogram. See 10.2(21).
6912 The main program has no parameters. It may be a procedure, or a function
6913 returning an integer type. In the latter case, the returned integer
6914 value is the return code of the program (overriding any value that
6915 may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}).
6920 @strong{36}. The mechanisms for building and running partitions. See
6924 GNAT itself supports programs with only a single partition. The GNATDIST
6925 tool provided with the GLADE package (which also includes an implementation
6926 of the PCS) provides a completely flexible method for building and running
6927 programs consisting of multiple partitions. See the separate GLADE manual
6933 @strong{37}. The details of program execution, including program
6934 termination. See 10.2(25).
6937 See separate section on compilation model.
6942 @strong{38}. The semantics of any non-active partitions supported by the
6943 implementation. See 10.2(28).
6946 Passive partitions are supported on targets where shared memory is
6947 provided by the operating system. See the GLADE reference manual for
6953 @strong{39}. The information returned by @code{Exception_Message}. See
6957 Exception message returns the null string unless a specific message has
6958 been passed by the program.
6963 @strong{40}. The result of @code{Exceptions.Exception_Name} for types
6964 declared within an unnamed @code{block_statement}. See 11.4.1(12).
6967 Blocks have implementation defined names of the form @code{B@var{nnn}}
6968 where @var{nnn} is an integer.
6973 @strong{41}. The information returned by
6974 @code{Exception_Information}. See 11.4.1(13).
6977 @code{Exception_Information} returns a string in the following format:
6980 @emph{Exception_Name:} nnnnn
6981 @emph{Message:} mmmmm
6983 @emph{Call stack traceback locations:}
6984 0xhhhh 0xhhhh 0xhhhh ... 0xhhh
6992 @code{nnnn} is the fully qualified name of the exception in all upper
6993 case letters. This line is always present.
6996 @code{mmmm} is the message (this line present only if message is non-null)
6999 @code{ppp} is the Process Id value as a decimal integer (this line is
7000 present only if the Process Id is non-zero). Currently we are
7001 not making use of this field.
7004 The Call stack traceback locations line and the following values
7005 are present only if at least one traceback location was recorded.
7006 The values are given in C style format, with lower case letters
7007 for a-f, and only as many digits present as are necessary.
7011 The line terminator sequence at the end of each line, including
7012 the last line is a single @code{LF} character (@code{16#0A#}).
7017 @strong{42}. Implementation-defined check names. See 11.5(27).
7020 No implementation-defined check names are supported.
7025 @strong{43}. The interpretation of each aspect of representation. See
7029 See separate section on data representations.
7034 @strong{44}. Any restrictions placed upon representation items. See
7038 See separate section on data representations.
7043 @strong{45}. The meaning of @code{Size} for indefinite subtypes. See
7047 Size for an indefinite subtype is the maximum possible size, except that
7048 for the case of a subprogram parameter, the size of the parameter object
7054 @strong{46}. The default external representation for a type tag. See
7058 The default external representation for a type tag is the fully expanded
7059 name of the type in upper case letters.
7064 @strong{47}. What determines whether a compilation unit is the same in
7065 two different partitions. See 13.3(76).
7068 A compilation unit is the same in two different partitions if and only
7069 if it derives from the same source file.
7074 @strong{48}. Implementation-defined components. See 13.5.1(15).
7077 The only implementation defined component is the tag for a tagged type,
7078 which contains a pointer to the dispatching table.
7083 @strong{49}. If @code{Word_Size} = @code{Storage_Unit}, the default bit
7084 ordering. See 13.5.3(5).
7087 @code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this
7088 implementation, so no non-default bit ordering is supported. The default
7089 bit ordering corresponds to the natural endianness of the target architecture.
7094 @strong{50}. The contents of the visible part of package @code{System}
7095 and its language-defined children. See 13.7(2).
7098 See the definition of these packages in files @file{system.ads} and
7099 @file{s-stoele.ads}.
7104 @strong{51}. The contents of the visible part of package
7105 @code{System.Machine_Code}, and the meaning of
7106 @code{code_statements}. See 13.8(7).
7109 See the definition and documentation in file @file{s-maccod.ads}.
7114 @strong{52}. The effect of unchecked conversion. See 13.9(11).
7117 Unchecked conversion between types of the same size
7118 and results in an uninterpreted transmission of the bits from one type
7119 to the other. If the types are of unequal sizes, then in the case of
7120 discrete types, a shorter source is first zero or sign extended as
7121 necessary, and a shorter target is simply truncated on the left.
7122 For all non-discrete types, the source is first copied if necessary
7123 to ensure that the alignment requirements of the target are met, then
7124 a pointer is constructed to the source value, and the result is obtained
7125 by dereferencing this pointer after converting it to be a pointer to the
7131 @strong{53}. The manner of choosing a storage pool for an access type
7132 when @code{Storage_Pool} is not specified for the type. See 13.11(17).
7135 There are 3 different standard pools used by the compiler when
7136 @code{Storage_Pool} is not specified depending whether the type is local
7137 to a subprogram or defined at the library level and whether
7138 @code{Storage_Size}is specified or not. See documentation in the runtime
7139 library units @code{System.Pool_Global}, @code{System.Pool_Size} and
7140 @code{System.Pool_Local} in files @file{s-poosiz.ads},
7141 @file{s-pooglo.ads} and @file{s-pooloc.ads} for full details on the
7147 @strong{54}. Whether or not the implementation provides user-accessible
7148 names for the standard pool type(s). See 13.11(17).
7152 See documentation in the sources of the run time mentioned in paragraph
7153 @strong{53} . All these pools are accessible by means of @code{with}'ing
7159 @strong{55}. The meaning of @code{Storage_Size}. See 13.11(18).
7162 @code{Storage_Size} is measured in storage units, and refers to the
7163 total space available for an access type collection, or to the primary
7164 stack space for a task.
7169 @strong{56}. Implementation-defined aspects of storage pools. See
7173 See documentation in the sources of the run time mentioned in paragraph
7174 @strong{53} for details on GNAT-defined aspects of storage pools.
7179 @strong{57}. The set of restrictions allowed in a pragma
7180 @code{Restrictions}. See 13.12(7).
7183 All RM defined Restriction identifiers are implemented. The following
7184 additional restriction identifiers are provided. There are two separate
7185 lists of implementation dependent restriction identifiers. The first
7186 set requires consistency throughout a partition (in other words, if the
7187 restriction identifier is used for any compilation unit in the partition,
7188 then all compilation units in the partition must obey the restriction.
7192 @item Simple_Barriers
7193 @findex Simple_Barriers
7194 This restriction ensures at compile time that barriers in entry declarations
7195 for protected types are restricted to either static boolean expressions or
7196 references to simple boolean variables defined in the private part of the
7197 protected type. No other form of entry barriers is permitted. This is one
7198 of the restrictions of the Ravenscar profile for limited tasking (see also
7199 pragma @code{Profile (Ravenscar)}).
7201 @item Max_Entry_Queue_Length => Expr
7202 @findex Max_Entry_Queue_Length
7203 This restriction is a declaration that any protected entry compiled in
7204 the scope of the restriction has at most the specified number of
7205 tasks waiting on the entry
7206 at any one time, and so no queue is required. This restriction is not
7207 checked at compile time. A program execution is erroneous if an attempt
7208 is made to queue more than the specified number of tasks on such an entry.
7212 This restriction ensures at compile time that there is no implicit or
7213 explicit dependence on the package @code{Ada.Calendar}.
7215 @item No_Direct_Boolean_Operators
7216 @findex No_Direct_Boolean_Operators
7217 This restriction ensures that no logical (and/or/xor) or comparison
7218 operators are used on operands of type Boolean (or any type derived
7219 from Boolean). This is intended for use in safety critical programs
7220 where the certification protocol requires the use of short-circuit
7221 (and then, or else) forms for all composite boolean operations.
7223 @item No_Dynamic_Attachment
7224 @findex No_Dynamic_Attachment
7225 This restriction ensures that there is no call to any of the operations
7226 defined in package Ada.Interrupts.
7228 @item No_Enumeration_Maps
7229 @findex No_Enumeration_Maps
7230 This restriction ensures at compile time that no operations requiring
7231 enumeration maps are used (that is Image and Value attributes applied
7232 to enumeration types).
7234 @item No_Entry_Calls_In_Elaboration_Code
7235 @findex No_Entry_Calls_In_Elaboration_Code
7236 This restriction ensures at compile time that no task or protected entry
7237 calls are made during elaboration code. As a result of the use of this
7238 restriction, the compiler can assume that no code past an accept statement
7239 in a task can be executed at elaboration time.
7241 @item No_Exception_Handlers
7242 @findex No_Exception_Handlers
7243 This restriction ensures at compile time that there are no explicit
7244 exception handlers. It also indicates that no exception propagation will
7245 be provided. In this mode, exceptions may be raised but will result in
7246 an immediate call to the last chance handler, a routine that the user
7247 must define with the following profile:
7249 procedure Last_Chance_Handler
7250 (Source_Location : System.Address; Line : Integer);
7251 pragma Export (C, Last_Chance_Handler,
7252 "__gnat_last_chance_handler");
7254 The parameter is a C null-terminated string representing a message to be
7255 associated with the exception (typically the source location of the raise
7256 statement generated by the compiler). The Line parameter when non-zero
7257 represents the line number in the source program where the raise occurs.
7259 @item No_Exception_Streams
7260 @findex No_Exception_Streams
7261 This restriction ensures at compile time that no stream operations for
7262 types Exception_Id or Exception_Occurrence are used. This also makes it
7263 impossible to pass exceptions to or from a partition with this restriction
7264 in a distributed environment. If this exception is active, then the generated
7265 code is simplified by omitting the otherwise-required global registration
7266 of exceptions when they are declared.
7268 @item No_Implicit_Conditionals
7269 @findex No_Implicit_Conditionals
7270 This restriction ensures that the generated code does not contain any
7271 implicit conditionals, either by modifying the generated code where possible,
7272 or by rejecting any construct that would otherwise generate an implicit
7273 conditional. Note that this check does not include run time constraint
7274 checks, which on some targets may generate implicit conditionals as
7275 well. To control the latter, constraint checks can be suppressed in the
7278 @item No_Implicit_Dynamic_Code
7279 @findex No_Implicit_Dynamic_Code
7280 This restriction prevents the compiler from building ``trampolines''.
7281 This is a structure that is built on the stack and contains dynamic
7282 code to be executed at run time. A trampoline is needed to indirectly
7283 address a nested subprogram (that is a subprogram that is not at the
7284 library level). The restriction prevents the use of any of the
7285 attributes @code{Address}, @code{Access} or @code{Unrestricted_Access}
7286 being applied to a subprogram that is not at the library level.
7288 @item No_Implicit_Loops
7289 @findex No_Implicit_Loops
7290 This restriction ensures that the generated code does not contain any
7291 implicit @code{for} loops, either by modifying
7292 the generated code where possible,
7293 or by rejecting any construct that would otherwise generate an implicit
7296 @item No_Initialize_Scalars
7297 @findex No_Initialize_Scalars
7298 This restriction ensures that no unit in the partition is compiled with
7299 pragma Initialize_Scalars. This allows the generation of more efficient
7300 code, and in particular eliminates dummy null initialization routines that
7301 are otherwise generated for some record and array types.
7303 @item No_Local_Protected_Objects
7304 @findex No_Local_Protected_Objects
7305 This restriction ensures at compile time that protected objects are
7306 only declared at the library level.
7308 @item No_Protected_Type_Allocators
7309 @findex No_Protected_Type_Allocators
7310 This restriction ensures at compile time that there are no allocator
7311 expressions that attempt to allocate protected objects.
7313 @item No_Secondary_Stack
7314 @findex No_Secondary_Stack
7315 This restriction ensures at compile time that the generated code does not
7316 contain any reference to the secondary stack. The secondary stack is used
7317 to implement functions returning unconstrained objects (arrays or records)
7320 @item No_Select_Statements
7321 @findex No_Select_Statements
7322 This restriction ensures at compile time no select statements of any kind
7323 are permitted, that is the keyword @code{select} may not appear.
7324 This is one of the restrictions of the Ravenscar
7325 profile for limited tasking (see also pragma @code{Profile (Ravenscar)}).
7327 @item No_Standard_Storage_Pools
7328 @findex No_Standard_Storage_Pools
7329 This restriction ensures at compile time that no access types
7330 use the standard default storage pool. Any access type declared must
7331 have an explicit Storage_Pool attribute defined specifying a
7332 user-defined storage pool.
7336 This restriction ensures at compile/bind time that there are no
7337 stream objects created (and therefore no actual stream operations).
7338 This restriction does not forbid dependences on the package
7339 @code{Ada.Streams}. So it is permissible to with
7340 @code{Ada.Streams} (or another package that does so itself)
7341 as long as no actual stream objects are created.
7343 @item No_Task_Attributes_Package
7344 @findex No_Task_Attributes_Package
7345 This restriction ensures at compile time that there are no implicit or
7346 explicit dependencies on the package @code{Ada.Task_Attributes}.
7348 @item No_Task_Termination
7349 @findex No_Task_Termination
7350 This restriction ensures at compile time that no terminate alternatives
7351 appear in any task body.
7355 This restriction prevents the declaration of tasks or task types throughout
7356 the partition. It is similar in effect to the use of @code{Max_Tasks => 0}
7357 except that violations are caught at compile time and cause an error message
7358 to be output either by the compiler or binder.
7360 @item No_Wide_Characters
7361 @findex No_Wide_Characters
7362 This restriction ensures at compile time that no uses of the types
7363 @code{Wide_Character} or @code{Wide_String} or corresponding wide
7365 appear, and that no wide or wide wide string or character literals
7366 appear in the program (that is literals representing characters not in
7367 type @code{Character}.
7369 @item Static_Priorities
7370 @findex Static_Priorities
7371 This restriction ensures at compile time that all priority expressions
7372 are static, and that there are no dependencies on the package
7373 @code{Ada.Dynamic_Priorities}.
7375 @item Static_Storage_Size
7376 @findex Static_Storage_Size
7377 This restriction ensures at compile time that any expression appearing
7378 in a Storage_Size pragma or attribute definition clause is static.
7383 The second set of implementation dependent restriction identifiers
7384 does not require partition-wide consistency.
7385 The restriction may be enforced for a single
7386 compilation unit without any effect on any of the
7387 other compilation units in the partition.
7391 @item No_Elaboration_Code
7392 @findex No_Elaboration_Code
7393 This restriction ensures at compile time that no elaboration code is
7394 generated. Note that this is not the same condition as is enforced
7395 by pragma @code{Preelaborate}. There are cases in which pragma
7396 @code{Preelaborate} still permits code to be generated (e.g.@: code
7397 to initialize a large array to all zeroes), and there are cases of units
7398 which do not meet the requirements for pragma @code{Preelaborate},
7399 but for which no elaboration code is generated. Generally, it is
7400 the case that preelaborable units will meet the restrictions, with
7401 the exception of large aggregates initialized with an others_clause,
7402 and exception declarations (which generate calls to a run-time
7403 registry procedure). Note that this restriction is enforced on
7404 a unit by unit basis, it need not be obeyed consistently
7405 throughout a partition.
7407 @item No_Entry_Queue
7408 @findex No_Entry_Queue
7409 This restriction is a declaration that any protected entry compiled in
7410 the scope of the restriction has at most one task waiting on the entry
7411 at any one time, and so no queue is required. This restriction is not
7412 checked at compile time. A program execution is erroneous if an attempt
7413 is made to queue a second task on such an entry.
7415 @item No_Implementation_Attributes
7416 @findex No_Implementation_Attributes
7417 This restriction checks at compile time that no GNAT-defined attributes
7418 are present. With this restriction, the only attributes that can be used
7419 are those defined in the Ada 95 Reference Manual.
7421 @item No_Implementation_Pragmas
7422 @findex No_Implementation_Pragmas
7423 This restriction checks at compile time that no GNAT-defined pragmas
7424 are present. With this restriction, the only pragmas that can be used
7425 are those defined in the Ada 95 Reference Manual.
7427 @item No_Implementation_Restrictions
7428 @findex No_Implementation_Restrictions
7429 This restriction checks at compile time that no GNAT-defined restriction
7430 identifiers (other than @code{No_Implementation_Restrictions} itself)
7431 are present. With this restriction, the only other restriction identifiers
7432 that can be used are those defined in the Ada 95 Reference Manual.
7439 @strong{58}. The consequences of violating limitations on
7440 @code{Restrictions} pragmas. See 13.12(9).
7443 Restrictions that can be checked at compile time result in illegalities
7444 if violated. Currently there are no other consequences of violating
7450 @strong{59}. The representation used by the @code{Read} and
7451 @code{Write} attributes of elementary types in terms of stream
7452 elements. See 13.13.2(9).
7455 The representation is the in-memory representation of the base type of
7456 the type, using the number of bits corresponding to the
7457 @code{@var{type}'Size} value, and the natural ordering of the machine.
7462 @strong{60}. The names and characteristics of the numeric subtypes
7463 declared in the visible part of package @code{Standard}. See A.1(3).
7466 See items describing the integer and floating-point types supported.
7471 @strong{61}. The accuracy actually achieved by the elementary
7472 functions. See A.5.1(1).
7475 The elementary functions correspond to the functions available in the C
7476 library. Only fast math mode is implemented.
7481 @strong{62}. The sign of a zero result from some of the operators or
7482 functions in @code{Numerics.Generic_Elementary_Functions}, when
7483 @code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46).
7486 The sign of zeroes follows the requirements of the IEEE 754 standard on
7492 @strong{63}. The value of
7493 @code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27).
7496 Maximum image width is 649, see library file @file{a-numran.ads}.
7501 @strong{64}. The value of
7502 @code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27).
7505 Maximum image width is 80, see library file @file{a-nudira.ads}.
7510 @strong{65}. The algorithms for random number generation. See
7514 The algorithm is documented in the source files @file{a-numran.ads} and
7515 @file{a-numran.adb}.
7520 @strong{66}. The string representation of a random number generator's
7521 state. See A.5.2(38).
7524 See the documentation contained in the file @file{a-numran.adb}.
7529 @strong{67}. The minimum time interval between calls to the
7530 time-dependent Reset procedure that are guaranteed to initiate different
7531 random number sequences. See A.5.2(45).
7534 The minimum period between reset calls to guarantee distinct series of
7535 random numbers is one microsecond.
7540 @strong{68}. The values of the @code{Model_Mantissa},
7541 @code{Model_Emin}, @code{Model_Epsilon}, @code{Model},
7542 @code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics
7543 Annex is not supported. See A.5.3(72).
7546 See the source file @file{ttypef.ads} for the values of all numeric
7552 @strong{69}. Any implementation-defined characteristics of the
7553 input-output packages. See A.7(14).
7556 There are no special implementation defined characteristics for these
7562 @strong{70}. The value of @code{Buffer_Size} in @code{Storage_IO}. See
7566 All type representations are contiguous, and the @code{Buffer_Size} is
7567 the value of @code{@var{type}'Size} rounded up to the next storage unit
7573 @strong{71}. External files for standard input, standard output, and
7574 standard error See A.10(5).
7577 These files are mapped onto the files provided by the C streams
7578 libraries. See source file @file{i-cstrea.ads} for further details.
7583 @strong{72}. The accuracy of the value produced by @code{Put}. See
7587 If more digits are requested in the output than are represented by the
7588 precision of the value, zeroes are output in the corresponding least
7589 significant digit positions.
7594 @strong{73}. The meaning of @code{Argument_Count}, @code{Argument}, and
7595 @code{Command_Name}. See A.15(1).
7598 These are mapped onto the @code{argv} and @code{argc} parameters of the
7599 main program in the natural manner.
7604 @strong{74}. Implementation-defined convention names. See B.1(11).
7607 The following convention names are supported
7615 Synonym for Assembler
7617 Synonym for Assembler
7620 @item C_Pass_By_Copy
7621 Allowed only for record types, like C, but also notes that record
7622 is to be passed by copy rather than reference.
7628 Treated the same as C
7630 Treated the same as C
7634 For support of pragma @code{Import} with convention Intrinsic, see
7635 separate section on Intrinsic Subprograms.
7637 Stdcall (used for Windows implementations only). This convention correspond
7638 to the WINAPI (previously called Pascal convention) C/C++ convention under
7639 Windows. A function with this convention cleans the stack before exit.
7645 Stubbed is a special convention used to indicate that the body of the
7646 subprogram will be entirely ignored. Any call to the subprogram
7647 is converted into a raise of the @code{Program_Error} exception. If a
7648 pragma @code{Import} specifies convention @code{stubbed} then no body need
7649 be present at all. This convention is useful during development for the
7650 inclusion of subprograms whose body has not yet been written.
7654 In addition, all otherwise unrecognized convention names are also
7655 treated as being synonymous with convention C@. In all implementations
7656 except for VMS, use of such other names results in a warning. In VMS
7657 implementations, these names are accepted silently.
7662 @strong{75}. The meaning of link names. See B.1(36).
7665 Link names are the actual names used by the linker.
7670 @strong{76}. The manner of choosing link names when neither the link
7671 name nor the address of an imported or exported entity is specified. See
7675 The default linker name is that which would be assigned by the relevant
7676 external language, interpreting the Ada name as being in all lower case
7682 @strong{77}. The effect of pragma @code{Linker_Options}. See B.1(37).
7685 The string passed to @code{Linker_Options} is presented uninterpreted as
7686 an argument to the link command, unless it contains Ascii.NUL characters.
7687 NUL characters if they appear act as argument separators, so for example
7689 @smallexample @c ada
7690 pragma Linker_Options ("-labc" & ASCII.Nul & "-ldef");
7694 causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the
7695 linker. The order of linker options is preserved for a given unit. The final
7696 list of options passed to the linker is in reverse order of the elaboration
7697 order. For example, linker options fo a body always appear before the options
7698 from the corresponding package spec.
7703 @strong{78}. The contents of the visible part of package
7704 @code{Interfaces} and its language-defined descendants. See B.2(1).
7707 See files with prefix @file{i-} in the distributed library.
7712 @strong{79}. Implementation-defined children of package
7713 @code{Interfaces}. The contents of the visible part of package
7714 @code{Interfaces}. See B.2(11).
7717 See files with prefix @file{i-} in the distributed library.
7722 @strong{80}. The types @code{Floating}, @code{Long_Floating},
7723 @code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and
7724 @code{COBOL_Character}; and the initialization of the variables
7725 @code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in
7726 @code{Interfaces.COBOL}. See B.4(50).
7733 (Floating) Long_Float
7738 @item Decimal_Element
7740 @item COBOL_Character
7745 For initialization, see the file @file{i-cobol.ads} in the distributed library.
7750 @strong{81}. Support for access to machine instructions. See C.1(1).
7753 See documentation in file @file{s-maccod.ads} in the distributed library.
7758 @strong{82}. Implementation-defined aspects of access to machine
7759 operations. See C.1(9).
7762 See documentation in file @file{s-maccod.ads} in the distributed library.
7767 @strong{83}. Implementation-defined aspects of interrupts. See C.3(2).
7770 Interrupts are mapped to signals or conditions as appropriate. See
7772 @code{Ada.Interrupt_Names} in source file @file{a-intnam.ads} for details
7773 on the interrupts supported on a particular target.
7778 @strong{84}. Implementation-defined aspects of pre-elaboration. See
7782 GNAT does not permit a partition to be restarted without reloading,
7783 except under control of the debugger.
7788 @strong{85}. The semantics of pragma @code{Discard_Names}. See C.5(7).
7791 Pragma @code{Discard_Names} causes names of enumeration literals to
7792 be suppressed. In the presence of this pragma, the Image attribute
7793 provides the image of the Pos of the literal, and Value accepts
7799 @strong{86}. The result of the @code{Task_Identification.Image}
7800 attribute. See C.7.1(7).
7803 The result of this attribute is an 8-digit hexadecimal string
7804 representing the virtual address of the task control block.
7809 @strong{87}. The value of @code{Current_Task} when in a protected entry
7810 or interrupt handler. See C.7.1(17).
7813 Protected entries or interrupt handlers can be executed by any
7814 convenient thread, so the value of @code{Current_Task} is undefined.
7819 @strong{88}. The effect of calling @code{Current_Task} from an entry
7820 body or interrupt handler. See C.7.1(19).
7823 The effect of calling @code{Current_Task} from an entry body or
7824 interrupt handler is to return the identification of the task currently
7830 @strong{89}. Implementation-defined aspects of
7831 @code{Task_Attributes}. See C.7.2(19).
7834 There are no implementation-defined aspects of @code{Task_Attributes}.
7839 @strong{90}. Values of all @code{Metrics}. See D(2).
7842 The metrics information for GNAT depends on the performance of the
7843 underlying operating system. The sources of the run-time for tasking
7844 implementation, together with the output from @code{-gnatG} can be
7845 used to determine the exact sequence of operating systems calls made
7846 to implement various tasking constructs. Together with appropriate
7847 information on the performance of the underlying operating system,
7848 on the exact target in use, this information can be used to determine
7849 the required metrics.
7854 @strong{91}. The declarations of @code{Any_Priority} and
7855 @code{Priority}. See D.1(11).
7858 See declarations in file @file{system.ads}.
7863 @strong{92}. Implementation-defined execution resources. See D.1(15).
7866 There are no implementation-defined execution resources.
7871 @strong{93}. Whether, on a multiprocessor, a task that is waiting for
7872 access to a protected object keeps its processor busy. See D.2.1(3).
7875 On a multi-processor, a task that is waiting for access to a protected
7876 object does not keep its processor busy.
7881 @strong{94}. The affect of implementation defined execution resources
7882 on task dispatching. See D.2.1(9).
7887 Tasks map to IRIX threads, and the dispatching policy is as defined by
7888 the IRIX implementation of threads.
7890 Tasks map to threads in the threads package used by GNAT@. Where possible
7891 and appropriate, these threads correspond to native threads of the
7892 underlying operating system.
7897 @strong{95}. Implementation-defined @code{policy_identifiers} allowed
7898 in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3).
7901 There are no implementation-defined policy-identifiers allowed in this
7907 @strong{96}. Implementation-defined aspects of priority inversion. See
7911 Execution of a task cannot be preempted by the implementation processing
7912 of delay expirations for lower priority tasks.
7917 @strong{97}. Implementation defined task dispatching. See D.2.2(18).
7922 Tasks map to IRIX threads, and the dispatching policy is as defied by
7923 the IRIX implementation of threads.
7925 The policy is the same as that of the underlying threads implementation.
7930 @strong{98}. Implementation-defined @code{policy_identifiers} allowed
7931 in a pragma @code{Locking_Policy}. See D.3(4).
7934 The only implementation defined policy permitted in GNAT is
7935 @code{Inheritance_Locking}. On targets that support this policy, locking
7936 is implemented by inheritance, i.e.@: the task owning the lock operates
7937 at a priority equal to the highest priority of any task currently
7938 requesting the lock.
7943 @strong{99}. Default ceiling priorities. See D.3(10).
7946 The ceiling priority of protected objects of the type
7947 @code{System.Interrupt_Priority'Last} as described in the Ada 95
7948 Reference Manual D.3(10),
7953 @strong{100}. The ceiling of any protected object used internally by
7954 the implementation. See D.3(16).
7957 The ceiling priority of internal protected objects is
7958 @code{System.Priority'Last}.
7963 @strong{101}. Implementation-defined queuing policies. See D.4(1).
7966 There are no implementation-defined queueing policies.
7971 @strong{102}. On a multiprocessor, any conditions that cause the
7972 completion of an aborted construct to be delayed later than what is
7973 specified for a single processor. See D.6(3).
7976 The semantics for abort on a multi-processor is the same as on a single
7977 processor, there are no further delays.
7982 @strong{103}. Any operations that implicitly require heap storage
7983 allocation. See D.7(8).
7986 The only operation that implicitly requires heap storage allocation is
7992 @strong{104}. Implementation-defined aspects of pragma
7993 @code{Restrictions}. See D.7(20).
7996 There are no such implementation-defined aspects.
8001 @strong{105}. Implementation-defined aspects of package
8002 @code{Real_Time}. See D.8(17).
8005 There are no implementation defined aspects of package @code{Real_Time}.
8010 @strong{106}. Implementation-defined aspects of
8011 @code{delay_statements}. See D.9(8).
8014 Any difference greater than one microsecond will cause the task to be
8015 delayed (see D.9(7)).
8020 @strong{107}. The upper bound on the duration of interrupt blocking
8021 caused by the implementation. See D.12(5).
8024 The upper bound is determined by the underlying operating system. In
8025 no cases is it more than 10 milliseconds.
8030 @strong{108}. The means for creating and executing distributed
8034 The GLADE package provides a utility GNATDIST for creating and executing
8035 distributed programs. See the GLADE reference manual for further details.
8040 @strong{109}. Any events that can result in a partition becoming
8041 inaccessible. See E.1(7).
8044 See the GLADE reference manual for full details on such events.
8049 @strong{110}. The scheduling policies, treatment of priorities, and
8050 management of shared resources between partitions in certain cases. See
8054 See the GLADE reference manual for full details on these aspects of
8055 multi-partition execution.
8060 @strong{111}. Events that cause the version of a compilation unit to
8064 Editing the source file of a compilation unit, or the source files of
8065 any units on which it is dependent in a significant way cause the version
8066 to change. No other actions cause the version number to change. All changes
8067 are significant except those which affect only layout, capitalization or
8073 @strong{112}. Whether the execution of the remote subprogram is
8074 immediately aborted as a result of cancellation. See E.4(13).
8077 See the GLADE reference manual for details on the effect of abort in
8078 a distributed application.
8083 @strong{113}. Implementation-defined aspects of the PCS@. See E.5(25).
8086 See the GLADE reference manual for a full description of all implementation
8087 defined aspects of the PCS@.
8092 @strong{114}. Implementation-defined interfaces in the PCS@. See
8096 See the GLADE reference manual for a full description of all
8097 implementation defined interfaces.
8102 @strong{115}. The values of named numbers in the package
8103 @code{Decimal}. See F.2(7).
8115 @item Max_Decimal_Digits
8122 @strong{116}. The value of @code{Max_Picture_Length} in the package
8123 @code{Text_IO.Editing}. See F.3.3(16).
8131 @strong{117}. The value of @code{Max_Picture_Length} in the package
8132 @code{Wide_Text_IO.Editing}. See F.3.4(5).
8140 @strong{118}. The accuracy actually achieved by the complex elementary
8141 functions and by other complex arithmetic operations. See G.1(1).
8144 Standard library functions are used for the complex arithmetic
8145 operations. Only fast math mode is currently supported.
8150 @strong{119}. The sign of a zero result (or a component thereof) from
8151 any operator or function in @code{Numerics.Generic_Complex_Types}, when
8152 @code{Real'Signed_Zeros} is True. See G.1.1(53).
8155 The signs of zero values are as recommended by the relevant
8156 implementation advice.
8161 @strong{120}. The sign of a zero result (or a component thereof) from
8162 any operator or function in
8163 @code{Numerics.Generic_Complex_Elementary_Functions}, when
8164 @code{Real'Signed_Zeros} is @code{True}. See G.1.2(45).
8167 The signs of zero values are as recommended by the relevant
8168 implementation advice.
8173 @strong{121}. Whether the strict mode or the relaxed mode is the
8174 default. See G.2(2).
8177 The strict mode is the default. There is no separate relaxed mode. GNAT
8178 provides a highly efficient implementation of strict mode.
8183 @strong{122}. The result interval in certain cases of fixed-to-float
8184 conversion. See G.2.1(10).
8187 For cases where the result interval is implementation dependent, the
8188 accuracy is that provided by performing all operations in 64-bit IEEE
8189 floating-point format.
8194 @strong{123}. The result of a floating point arithmetic operation in
8195 overflow situations, when the @code{Machine_Overflows} attribute of the
8196 result type is @code{False}. See G.2.1(13).
8199 Infinite and Nan values are produced as dictated by the IEEE
8200 floating-point standard.
8205 @strong{124}. The result interval for division (or exponentiation by a
8206 negative exponent), when the floating point hardware implements division
8207 as multiplication by a reciprocal. See G.2.1(16).
8210 Not relevant, division is IEEE exact.
8215 @strong{125}. The definition of close result set, which determines the
8216 accuracy of certain fixed point multiplications and divisions. See
8220 Operations in the close result set are performed using IEEE long format
8221 floating-point arithmetic. The input operands are converted to
8222 floating-point, the operation is done in floating-point, and the result
8223 is converted to the target type.
8228 @strong{126}. Conditions on a @code{universal_real} operand of a fixed
8229 point multiplication or division for which the result shall be in the
8230 perfect result set. See G.2.3(22).
8233 The result is only defined to be in the perfect result set if the result
8234 can be computed by a single scaling operation involving a scale factor
8235 representable in 64-bits.
8240 @strong{127}. The result of a fixed point arithmetic operation in
8241 overflow situations, when the @code{Machine_Overflows} attribute of the
8242 result type is @code{False}. See G.2.3(27).
8245 Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point
8251 @strong{128}. The result of an elementary function reference in
8252 overflow situations, when the @code{Machine_Overflows} attribute of the
8253 result type is @code{False}. See G.2.4(4).
8256 IEEE infinite and Nan values are produced as appropriate.
8261 @strong{129}. The value of the angle threshold, within which certain
8262 elementary functions, complex arithmetic operations, and complex
8263 elementary functions yield results conforming to a maximum relative
8264 error bound. See G.2.4(10).
8267 Information on this subject is not yet available.
8272 @strong{130}. The accuracy of certain elementary functions for
8273 parameters beyond the angle threshold. See G.2.4(10).
8276 Information on this subject is not yet available.
8281 @strong{131}. The result of a complex arithmetic operation or complex
8282 elementary function reference in overflow situations, when the
8283 @code{Machine_Overflows} attribute of the corresponding real type is
8284 @code{False}. See G.2.6(5).
8287 IEEE infinite and Nan values are produced as appropriate.
8292 @strong{132}. The accuracy of certain complex arithmetic operations and
8293 certain complex elementary functions for parameters (or components
8294 thereof) beyond the angle threshold. See G.2.6(8).
8297 Information on those subjects is not yet available.
8302 @strong{133}. Information regarding bounded errors and erroneous
8303 execution. See H.2(1).
8306 Information on this subject is not yet available.
8311 @strong{134}. Implementation-defined aspects of pragma
8312 @code{Inspection_Point}. See H.3.2(8).
8315 Pragma @code{Inspection_Point} ensures that the variable is live and can
8316 be examined by the debugger at the inspection point.
8321 @strong{135}. Implementation-defined aspects of pragma
8322 @code{Restrictions}. See H.4(25).
8325 There are no implementation-defined aspects of pragma @code{Restrictions}. The
8326 use of pragma @code{Restrictions [No_Exceptions]} has no effect on the
8327 generated code. Checks must suppressed by use of pragma @code{Suppress}.
8332 @strong{136}. Any restrictions on pragma @code{Restrictions}. See
8336 There are no restrictions on pragma @code{Restrictions}.
8338 @node Intrinsic Subprograms
8339 @chapter Intrinsic Subprograms
8340 @cindex Intrinsic Subprograms
8343 * Intrinsic Operators::
8344 * Enclosing_Entity::
8345 * Exception_Information::
8346 * Exception_Message::
8354 * Shift_Right_Arithmetic::
8359 GNAT allows a user application program to write the declaration:
8361 @smallexample @c ada
8362 pragma Import (Intrinsic, name);
8366 providing that the name corresponds to one of the implemented intrinsic
8367 subprograms in GNAT, and that the parameter profile of the referenced
8368 subprogram meets the requirements. This chapter describes the set of
8369 implemented intrinsic subprograms, and the requirements on parameter profiles.
8370 Note that no body is supplied; as with other uses of pragma Import, the
8371 body is supplied elsewhere (in this case by the compiler itself). Note
8372 that any use of this feature is potentially non-portable, since the
8373 Ada standard does not require Ada compilers to implement this feature.
8375 @node Intrinsic Operators
8376 @section Intrinsic Operators
8377 @cindex Intrinsic operator
8380 All the predefined numeric operators in package Standard
8381 in @code{pragma Import (Intrinsic,..)}
8382 declarations. In the binary operator case, the operands must have the same
8383 size. The operand or operands must also be appropriate for
8384 the operator. For example, for addition, the operands must
8385 both be floating-point or both be fixed-point, and the
8386 right operand for @code{"**"} must have a root type of
8387 @code{Standard.Integer'Base}.
8388 You can use an intrinsic operator declaration as in the following example:
8390 @smallexample @c ada
8391 type Int1 is new Integer;
8392 type Int2 is new Integer;
8394 function "+" (X1 : Int1; X2 : Int2) return Int1;
8395 function "+" (X1 : Int1; X2 : Int2) return Int2;
8396 pragma Import (Intrinsic, "+");
8400 This declaration would permit ``mixed mode'' arithmetic on items
8401 of the differing types @code{Int1} and @code{Int2}.
8402 It is also possible to specify such operators for private types, if the
8403 full views are appropriate arithmetic types.
8405 @node Enclosing_Entity
8406 @section Enclosing_Entity
8407 @cindex Enclosing_Entity
8409 This intrinsic subprogram is used in the implementation of the
8410 library routine @code{GNAT.Source_Info}. The only useful use of the
8411 intrinsic import in this case is the one in this unit, so an
8412 application program should simply call the function
8413 @code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of
8414 the current subprogram, package, task, entry, or protected subprogram.
8416 @node Exception_Information
8417 @section Exception_Information
8418 @cindex Exception_Information'
8420 This intrinsic subprogram is used in the implementation of the
8421 library routine @code{GNAT.Current_Exception}. The only useful
8422 use of the intrinsic import in this case is the one in this unit,
8423 so an application program should simply call the function
8424 @code{GNAT.Current_Exception.Exception_Information} to obtain
8425 the exception information associated with the current exception.
8427 @node Exception_Message
8428 @section Exception_Message
8429 @cindex Exception_Message
8431 This intrinsic subprogram is used in the implementation of the
8432 library routine @code{GNAT.Current_Exception}. The only useful
8433 use of the intrinsic import in this case is the one in this unit,
8434 so an application program should simply call the function
8435 @code{GNAT.Current_Exception.Exception_Message} to obtain
8436 the message associated with the current exception.
8438 @node Exception_Name
8439 @section Exception_Name
8440 @cindex Exception_Name
8442 This intrinsic subprogram is used in the implementation of the
8443 library routine @code{GNAT.Current_Exception}. The only useful
8444 use of the intrinsic import in this case is the one in this unit,
8445 so an application program should simply call the function
8446 @code{GNAT.Current_Exception.Exception_Name} to obtain
8447 the name of the current exception.
8453 This intrinsic subprogram is used in the implementation of the
8454 library routine @code{GNAT.Source_Info}. The only useful use of the
8455 intrinsic import in this case is the one in this unit, so an
8456 application program should simply call the function
8457 @code{GNAT.Source_Info.File} to obtain the name of the current
8464 This intrinsic subprogram is used in the implementation of the
8465 library routine @code{GNAT.Source_Info}. The only useful use of the
8466 intrinsic import in this case is the one in this unit, so an
8467 application program should simply call the function
8468 @code{GNAT.Source_Info.Line} to obtain the number of the current
8472 @section Rotate_Left
8475 In standard Ada 95, the @code{Rotate_Left} function is available only
8476 for the predefined modular types in package @code{Interfaces}. However, in
8477 GNAT it is possible to define a Rotate_Left function for a user
8478 defined modular type or any signed integer type as in this example:
8480 @smallexample @c ada
8482 (Value : My_Modular_Type;
8484 return My_Modular_Type;
8488 The requirements are that the profile be exactly as in the example
8489 above. The only modifications allowed are in the formal parameter
8490 names, and in the type of @code{Value} and the return type, which
8491 must be the same, and must be either a signed integer type, or
8492 a modular integer type with a binary modulus, and the size must
8493 be 8. 16, 32 or 64 bits.
8496 @section Rotate_Right
8497 @cindex Rotate_Right
8499 A @code{Rotate_Right} function can be defined for any user defined
8500 binary modular integer type, or signed integer type, as described
8501 above for @code{Rotate_Left}.
8507 A @code{Shift_Left} function can be defined for any user defined
8508 binary modular integer type, or signed integer type, as described
8509 above for @code{Rotate_Left}.
8512 @section Shift_Right
8515 A @code{Shift_Right} function can be defined for any user defined
8516 binary modular integer type, or signed integer type, as described
8517 above for @code{Rotate_Left}.
8519 @node Shift_Right_Arithmetic
8520 @section Shift_Right_Arithmetic
8521 @cindex Shift_Right_Arithmetic
8523 A @code{Shift_Right_Arithmetic} function can be defined for any user
8524 defined binary modular integer type, or signed integer type, as described
8525 above for @code{Rotate_Left}.
8527 @node Source_Location
8528 @section Source_Location
8529 @cindex Source_Location
8531 This intrinsic subprogram is used in the implementation of the
8532 library routine @code{GNAT.Source_Info}. The only useful use of the
8533 intrinsic import in this case is the one in this unit, so an
8534 application program should simply call the function
8535 @code{GNAT.Source_Info.Source_Location} to obtain the current
8536 source file location.
8538 @node Representation Clauses and Pragmas
8539 @chapter Representation Clauses and Pragmas
8540 @cindex Representation Clauses
8543 * Alignment Clauses::
8545 * Storage_Size Clauses::
8546 * Size of Variant Record Objects::
8547 * Biased Representation ::
8548 * Value_Size and Object_Size Clauses::
8549 * Component_Size Clauses::
8550 * Bit_Order Clauses::
8551 * Effect of Bit_Order on Byte Ordering::
8552 * Pragma Pack for Arrays::
8553 * Pragma Pack for Records::
8554 * Record Representation Clauses::
8555 * Enumeration Clauses::
8557 * Effect of Convention on Representation::
8558 * Determining the Representations chosen by GNAT::
8562 @cindex Representation Clause
8563 @cindex Representation Pragma
8564 @cindex Pragma, representation
8565 This section describes the representation clauses accepted by GNAT, and
8566 their effect on the representation of corresponding data objects.
8568 GNAT fully implements Annex C (Systems Programming). This means that all
8569 the implementation advice sections in chapter 13 are fully implemented.
8570 However, these sections only require a minimal level of support for
8571 representation clauses. GNAT provides much more extensive capabilities,
8572 and this section describes the additional capabilities provided.
8574 @node Alignment Clauses
8575 @section Alignment Clauses
8576 @cindex Alignment Clause
8579 GNAT requires that all alignment clauses specify a power of 2, and all
8580 default alignments are always a power of 2. The default alignment
8581 values are as follows:
8584 @item @emph{Primitive Types}.
8585 For primitive types, the alignment is the minimum of the actual size of
8586 objects of the type divided by @code{Storage_Unit},
8587 and the maximum alignment supported by the target.
8588 (This maximum alignment is given by the GNAT-specific attribute
8589 @code{Standard'Maximum_Alignment}; see @ref{Maximum_Alignment}.)
8590 @cindex @code{Maximum_Alignment} attribute
8591 For example, for type @code{Long_Float}, the object size is 8 bytes, and the
8592 default alignment will be 8 on any target that supports alignments
8593 this large, but on some targets, the maximum alignment may be smaller
8594 than 8, in which case objects of type @code{Long_Float} will be maximally
8597 @item @emph{Arrays}.
8598 For arrays, the alignment is equal to the alignment of the component type
8599 for the normal case where no packing or component size is given. If the
8600 array is packed, and the packing is effective (see separate section on
8601 packed arrays), then the alignment will be one for long packed arrays,
8602 or arrays whose length is not known at compile time. For short packed
8603 arrays, which are handled internally as modular types, the alignment
8604 will be as described for primitive types, e.g.@: a packed array of length
8605 31 bits will have an object size of four bytes, and an alignment of 4.
8607 @item @emph{Records}.
8608 For the normal non-packed case, the alignment of a record is equal to
8609 the maximum alignment of any of its components. For tagged records, this
8610 includes the implicit access type used for the tag. If a pragma @code{Pack} is
8611 used and all fields are packable (see separate section on pragma @code{Pack}),
8612 then the resulting alignment is 1.
8614 A special case is when:
8617 the size of the record is given explicitly, or a
8618 full record representation clause is given, and
8620 the size of the record is 2, 4, or 8 bytes.
8623 In this case, an alignment is chosen to match the
8624 size of the record. For example, if we have:
8626 @smallexample @c ada
8627 type Small is record
8630 for Small'Size use 16;
8634 then the default alignment of the record type @code{Small} is 2, not 1. This
8635 leads to more efficient code when the record is treated as a unit, and also
8636 allows the type to specified as @code{Atomic} on architectures requiring
8642 An alignment clause may
8643 always specify a larger alignment than the default value, up to some
8644 maximum value dependent on the target (obtainable by using the
8645 attribute reference @code{Standard'Maximum_Alignment}).
8647 it is permissible to specify a smaller alignment than the default value
8648 is for a record with a record representation clause.
8649 In this case, packable fields for which a component clause is
8650 given still result in a default alignment corresponding to the original
8651 type, but this may be overridden, since these components in fact only
8652 require an alignment of one byte. For example, given
8654 @smallexample @c ada
8660 A at 0 range 0 .. 31;
8663 for V'alignment use 1;
8667 @cindex Alignment, default
8668 The default alignment for the type @code{V} is 4, as a result of the
8669 Integer field in the record, but since this field is placed with a
8670 component clause, it is permissible, as shown, to override the default
8671 alignment of the record with a smaller value.
8674 @section Size Clauses
8678 The default size for a type @code{T} is obtainable through the
8679 language-defined attribute @code{T'Size} and also through the
8680 equivalent GNAT-defined attribute @code{T'Value_Size}.
8681 For objects of type @code{T}, GNAT will generally increase the type size
8682 so that the object size (obtainable through the GNAT-defined attribute
8683 @code{T'Object_Size})
8684 is a multiple of @code{T'Alignment * Storage_Unit}.
8687 @smallexample @c ada
8688 type Smallint is range 1 .. 6;
8697 In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3,
8698 as specified by the RM rules,
8699 but objects of this type will have a size of 8
8700 (@code{Smallint'Object_Size} = 8),
8701 since objects by default occupy an integral number
8702 of storage units. On some targets, notably older
8703 versions of the Digital Alpha, the size of stand
8704 alone objects of this type may be 32, reflecting
8705 the inability of the hardware to do byte load/stores.
8707 Similarly, the size of type @code{Rec} is 40 bits
8708 (@code{Rec'Size} = @code{Rec'Value_Size} = 40), but
8709 the alignment is 4, so objects of this type will have
8710 their size increased to 64 bits so that it is a multiple
8711 of the alignment (in bits). This decision is
8712 in accordance with the specific Implementation Advice in RM 13.3(43):
8715 A @code{Size} clause should be supported for an object if the specified
8716 @code{Size} is at least as large as its subtype's @code{Size}, and corresponds
8717 to a size in storage elements that is a multiple of the object's
8718 @code{Alignment} (if the @code{Alignment} is nonzero).
8722 An explicit size clause may be used to override the default size by
8723 increasing it. For example, if we have:
8725 @smallexample @c ada
8726 type My_Boolean is new Boolean;
8727 for My_Boolean'Size use 32;
8731 then values of this type will always be 32 bits long. In the case of
8732 discrete types, the size can be increased up to 64 bits, with the effect
8733 that the entire specified field is used to hold the value, sign- or
8734 zero-extended as appropriate. If more than 64 bits is specified, then
8735 padding space is allocated after the value, and a warning is issued that
8736 there are unused bits.
8738 Similarly the size of records and arrays may be increased, and the effect
8739 is to add padding bits after the value. This also causes a warning message
8742 The largest Size value permitted in GNAT is 2**31@minus{}1. Since this is a
8743 Size in bits, this corresponds to an object of size 256 megabytes (minus
8744 one). This limitation is true on all targets. The reason for this
8745 limitation is that it improves the quality of the code in many cases
8746 if it is known that a Size value can be accommodated in an object of
8749 @node Storage_Size Clauses
8750 @section Storage_Size Clauses
8751 @cindex Storage_Size Clause
8754 For tasks, the @code{Storage_Size} clause specifies the amount of space
8755 to be allocated for the task stack. This cannot be extended, and if the
8756 stack is exhausted, then @code{Storage_Error} will be raised (if stack
8757 checking is enabled). Use a @code{Storage_Size} attribute definition clause,
8758 or a @code{Storage_Size} pragma in the task definition to set the
8759 appropriate required size. A useful technique is to include in every
8760 task definition a pragma of the form:
8762 @smallexample @c ada
8763 pragma Storage_Size (Default_Stack_Size);
8767 Then @code{Default_Stack_Size} can be defined in a global package, and
8768 modified as required. Any tasks requiring stack sizes different from the
8769 default can have an appropriate alternative reference in the pragma.
8771 For access types, the @code{Storage_Size} clause specifies the maximum
8772 space available for allocation of objects of the type. If this space is
8773 exceeded then @code{Storage_Error} will be raised by an allocation attempt.
8774 In the case where the access type is declared local to a subprogram, the
8775 use of a @code{Storage_Size} clause triggers automatic use of a special
8776 predefined storage pool (@code{System.Pool_Size}) that ensures that all
8777 space for the pool is automatically reclaimed on exit from the scope in
8778 which the type is declared.
8780 A special case recognized by the compiler is the specification of a
8781 @code{Storage_Size} of zero for an access type. This means that no
8782 items can be allocated from the pool, and this is recognized at compile
8783 time, and all the overhead normally associated with maintaining a fixed
8784 size storage pool is eliminated. Consider the following example:
8786 @smallexample @c ada
8788 type R is array (Natural) of Character;
8789 type P is access all R;
8790 for P'Storage_Size use 0;
8791 -- Above access type intended only for interfacing purposes
8795 procedure g (m : P);
8796 pragma Import (C, g);
8807 As indicated in this example, these dummy storage pools are often useful in
8808 connection with interfacing where no object will ever be allocated. If you
8809 compile the above example, you get the warning:
8812 p.adb:16:09: warning: allocation from empty storage pool
8813 p.adb:16:09: warning: Storage_Error will be raised at run time
8817 Of course in practice, there will not be any explicit allocators in the
8818 case of such an access declaration.
8820 @node Size of Variant Record Objects
8821 @section Size of Variant Record Objects
8822 @cindex Size, variant record objects
8823 @cindex Variant record objects, size
8826 In the case of variant record objects, there is a question whether Size gives
8827 information about a particular variant, or the maximum size required
8828 for any variant. Consider the following program
8830 @smallexample @c ada
8831 with Text_IO; use Text_IO;
8833 type R1 (A : Boolean := False) is record
8835 when True => X : Character;
8844 Put_Line (Integer'Image (V1'Size));
8845 Put_Line (Integer'Image (V2'Size));
8850 Here we are dealing with a variant record, where the True variant
8851 requires 16 bits, and the False variant requires 8 bits.
8852 In the above example, both V1 and V2 contain the False variant,
8853 which is only 8 bits long. However, the result of running the
8862 The reason for the difference here is that the discriminant value of
8863 V1 is fixed, and will always be False. It is not possible to assign
8864 a True variant value to V1, therefore 8 bits is sufficient. On the
8865 other hand, in the case of V2, the initial discriminant value is
8866 False (from the default), but it is possible to assign a True
8867 variant value to V2, therefore 16 bits must be allocated for V2
8868 in the general case, even fewer bits may be needed at any particular
8869 point during the program execution.
8871 As can be seen from the output of this program, the @code{'Size}
8872 attribute applied to such an object in GNAT gives the actual allocated
8873 size of the variable, which is the largest size of any of the variants.
8874 The Ada Reference Manual is not completely clear on what choice should
8875 be made here, but the GNAT behavior seems most consistent with the
8876 language in the RM@.
8878 In some cases, it may be desirable to obtain the size of the current
8879 variant, rather than the size of the largest variant. This can be
8880 achieved in GNAT by making use of the fact that in the case of a
8881 subprogram parameter, GNAT does indeed return the size of the current
8882 variant (because a subprogram has no way of knowing how much space
8883 is actually allocated for the actual).
8885 Consider the following modified version of the above program:
8887 @smallexample @c ada
8888 with Text_IO; use Text_IO;
8890 type R1 (A : Boolean := False) is record
8892 when True => X : Character;
8899 function Size (V : R1) return Integer is
8905 Put_Line (Integer'Image (V2'Size));
8906 Put_Line (Integer'IMage (Size (V2)));
8908 Put_Line (Integer'Image (V2'Size));
8909 Put_Line (Integer'IMage (Size (V2)));
8914 The output from this program is
8924 Here we see that while the @code{'Size} attribute always returns
8925 the maximum size, regardless of the current variant value, the
8926 @code{Size} function does indeed return the size of the current
8929 @node Biased Representation
8930 @section Biased Representation
8931 @cindex Size for biased representation
8932 @cindex Biased representation
8935 In the case of scalars with a range starting at other than zero, it is
8936 possible in some cases to specify a size smaller than the default minimum
8937 value, and in such cases, GNAT uses an unsigned biased representation,
8938 in which zero is used to represent the lower bound, and successive values
8939 represent successive values of the type.
8941 For example, suppose we have the declaration:
8943 @smallexample @c ada
8944 type Small is range -7 .. -4;
8945 for Small'Size use 2;
8949 Although the default size of type @code{Small} is 4, the @code{Size}
8950 clause is accepted by GNAT and results in the following representation
8954 -7 is represented as 2#00#
8955 -6 is represented as 2#01#
8956 -5 is represented as 2#10#
8957 -4 is represented as 2#11#
8961 Biased representation is only used if the specified @code{Size} clause
8962 cannot be accepted in any other manner. These reduced sizes that force
8963 biased representation can be used for all discrete types except for
8964 enumeration types for which a representation clause is given.
8966 @node Value_Size and Object_Size Clauses
8967 @section Value_Size and Object_Size Clauses
8970 @cindex Size, of objects
8973 In Ada 95, @code{T'Size} for a type @code{T} is the minimum number of bits
8974 required to hold values of type @code{T}. Although this interpretation was
8975 allowed in Ada 83, it was not required, and this requirement in practice
8976 can cause some significant difficulties. For example, in most Ada 83
8977 compilers, @code{Natural'Size} was 32. However, in Ada 95,
8978 @code{Natural'Size} is
8979 typically 31. This means that code may change in behavior when moving
8980 from Ada 83 to Ada 95. For example, consider:
8982 @smallexample @c ada
8989 at 0 range 0 .. Natural'Size - 1;
8990 at 0 range Natural'Size .. 2 * Natural'Size - 1;
8995 In the above code, since the typical size of @code{Natural} objects
8996 is 32 bits and @code{Natural'Size} is 31, the above code can cause
8997 unexpected inefficient packing in Ada 95, and in general there are
8998 cases where the fact that the object size can exceed the
8999 size of the type causes surprises.
9001 To help get around this problem GNAT provides two implementation
9002 defined attributes, @code{Value_Size} and @code{Object_Size}. When
9003 applied to a type, these attributes yield the size of the type
9004 (corresponding to the RM defined size attribute), and the size of
9005 objects of the type respectively.
9007 The @code{Object_Size} is used for determining the default size of
9008 objects and components. This size value can be referred to using the
9009 @code{Object_Size} attribute. The phrase ``is used'' here means that it is
9010 the basis of the determination of the size. The backend is free to
9011 pad this up if necessary for efficiency, e.g.@: an 8-bit stand-alone
9012 character might be stored in 32 bits on a machine with no efficient
9013 byte access instructions such as the Alpha.
9015 The default rules for the value of @code{Object_Size} for
9016 discrete types are as follows:
9020 The @code{Object_Size} for base subtypes reflect the natural hardware
9021 size in bits (run the compiler with @option{-gnatS} to find those values
9022 for numeric types). Enumeration types and fixed-point base subtypes have
9023 8, 16, 32 or 64 bits for this size, depending on the range of values
9027 The @code{Object_Size} of a subtype is the same as the
9028 @code{Object_Size} of
9029 the type from which it is obtained.
9032 The @code{Object_Size} of a derived base type is copied from the parent
9033 base type, and the @code{Object_Size} of a derived first subtype is copied
9034 from the parent first subtype.
9038 The @code{Value_Size} attribute
9039 is the (minimum) number of bits required to store a value
9041 This value is used to determine how tightly to pack
9042 records or arrays with components of this type, and also affects
9043 the semantics of unchecked conversion (unchecked conversions where
9044 the @code{Value_Size} values differ generate a warning, and are potentially
9047 The default rules for the value of @code{Value_Size} are as follows:
9051 The @code{Value_Size} for a base subtype is the minimum number of bits
9052 required to store all values of the type (including the sign bit
9053 only if negative values are possible).
9056 If a subtype statically matches the first subtype of a given type, then it has
9057 by default the same @code{Value_Size} as the first subtype. This is a
9058 consequence of RM 13.1(14) (``if two subtypes statically match,
9059 then their subtype-specific aspects are the same''.)
9062 All other subtypes have a @code{Value_Size} corresponding to the minimum
9063 number of bits required to store all values of the subtype. For
9064 dynamic bounds, it is assumed that the value can range down or up
9065 to the corresponding bound of the ancestor
9069 The RM defined attribute @code{Size} corresponds to the
9070 @code{Value_Size} attribute.
9072 The @code{Size} attribute may be defined for a first-named subtype. This sets
9073 the @code{Value_Size} of
9074 the first-named subtype to the given value, and the
9075 @code{Object_Size} of this first-named subtype to the given value padded up
9076 to an appropriate boundary. It is a consequence of the default rules
9077 above that this @code{Object_Size} will apply to all further subtypes. On the
9078 other hand, @code{Value_Size} is affected only for the first subtype, any
9079 dynamic subtypes obtained from it directly, and any statically matching
9080 subtypes. The @code{Value_Size} of any other static subtypes is not affected.
9082 @code{Value_Size} and
9083 @code{Object_Size} may be explicitly set for any subtype using
9084 an attribute definition clause. Note that the use of these attributes
9085 can cause the RM 13.1(14) rule to be violated. If two access types
9086 reference aliased objects whose subtypes have differing @code{Object_Size}
9087 values as a result of explicit attribute definition clauses, then it
9088 is erroneous to convert from one access subtype to the other.
9090 At the implementation level, Esize stores the Object_Size and the
9091 RM_Size field stores the @code{Value_Size} (and hence the value of the
9092 @code{Size} attribute,
9093 which, as noted above, is equivalent to @code{Value_Size}).
9095 To get a feel for the difference, consider the following examples (note
9096 that in each case the base is @code{Short_Short_Integer} with a size of 8):
9099 Object_Size Value_Size
9101 type x1 is range 0 .. 5; 8 3
9103 type x2 is range 0 .. 5;
9104 for x2'size use 12; 16 12
9106 subtype x3 is x2 range 0 .. 3; 16 2
9108 subtype x4 is x2'base range 0 .. 10; 8 4
9110 subtype x5 is x2 range 0 .. dynamic; 16 3*
9112 subtype x6 is x2'base range 0 .. dynamic; 8 3*
9117 Note: the entries marked ``3*'' are not actually specified by the Ada 95 RM,
9118 but it seems in the spirit of the RM rules to allocate the minimum number
9119 of bits (here 3, given the range for @code{x2})
9120 known to be large enough to hold the given range of values.
9122 So far, so good, but GNAT has to obey the RM rules, so the question is
9123 under what conditions must the RM @code{Size} be used.
9124 The following is a list
9125 of the occasions on which the RM @code{Size} must be used:
9129 Component size for packed arrays or records
9132 Value of the attribute @code{Size} for a type
9135 Warning about sizes not matching for unchecked conversion
9139 For record types, the @code{Object_Size} is always a multiple of the
9140 alignment of the type (this is true for all types). In some cases the
9141 @code{Value_Size} can be smaller. Consider:
9151 On a typical 32-bit architecture, the X component will be four bytes, and
9152 require four-byte alignment, and the Y component will be one byte. In this
9153 case @code{R'Value_Size} will be 40 (bits) since this is the minimum size
9154 required to store a value of this type, and for example, it is permissible
9155 to have a component of type R in an outer record whose component size is
9156 specified to be 48 bits. However, @code{R'Object_Size} will be 64 (bits),
9157 since it must be rounded up so that this value is a multiple of the
9158 alignment (4 bytes = 32 bits).
9161 For all other types, the @code{Object_Size}
9162 and Value_Size are the same (and equivalent to the RM attribute @code{Size}).
9163 Only @code{Size} may be specified for such types.
9165 @node Component_Size Clauses
9166 @section Component_Size Clauses
9167 @cindex Component_Size Clause
9170 Normally, the value specified in a component clause must be consistent
9171 with the subtype of the array component with regard to size and alignment.
9172 In other words, the value specified must be at least equal to the size
9173 of this subtype, and must be a multiple of the alignment value.
9175 In addition, component size clauses are allowed which cause the array
9176 to be packed, by specifying a smaller value. The cases in which this
9177 is allowed are for component size values in the range 1 through 63. The value
9178 specified must not be smaller than the Size of the subtype. GNAT will
9179 accurately honor all packing requests in this range. For example, if
9182 @smallexample @c ada
9183 type r is array (1 .. 8) of Natural;
9184 for r'Component_Size use 31;
9188 then the resulting array has a length of 31 bytes (248 bits = 8 * 31).
9189 Of course access to the components of such an array is considerably
9190 less efficient than if the natural component size of 32 is used.
9192 @node Bit_Order Clauses
9193 @section Bit_Order Clauses
9194 @cindex Bit_Order Clause
9195 @cindex bit ordering
9196 @cindex ordering, of bits
9199 For record subtypes, GNAT permits the specification of the @code{Bit_Order}
9200 attribute. The specification may either correspond to the default bit
9201 order for the target, in which case the specification has no effect and
9202 places no additional restrictions, or it may be for the non-standard
9203 setting (that is the opposite of the default).
9205 In the case where the non-standard value is specified, the effect is
9206 to renumber bits within each byte, but the ordering of bytes is not
9207 affected. There are certain
9208 restrictions placed on component clauses as follows:
9212 @item Components fitting within a single storage unit.
9214 These are unrestricted, and the effect is merely to renumber bits. For
9215 example if we are on a little-endian machine with @code{Low_Order_First}
9216 being the default, then the following two declarations have exactly
9219 @smallexample @c ada
9222 B : Integer range 1 .. 120;
9226 A at 0 range 0 .. 0;
9227 B at 0 range 1 .. 7;
9232 B : Integer range 1 .. 120;
9235 for R2'Bit_Order use High_Order_First;
9238 A at 0 range 7 .. 7;
9239 B at 0 range 0 .. 6;
9244 The useful application here is to write the second declaration with the
9245 @code{Bit_Order} attribute definition clause, and know that it will be treated
9246 the same, regardless of whether the target is little-endian or big-endian.
9248 @item Components occupying an integral number of bytes.
9250 These are components that exactly fit in two or more bytes. Such component
9251 declarations are allowed, but have no effect, since it is important to realize
9252 that the @code{Bit_Order} specification does not affect the ordering of bytes.
9253 In particular, the following attempt at getting an endian-independent integer
9256 @smallexample @c ada
9261 for R2'Bit_Order use High_Order_First;
9264 A at 0 range 0 .. 31;
9269 This declaration will result in a little-endian integer on a
9270 little-endian machine, and a big-endian integer on a big-endian machine.
9271 If byte flipping is required for interoperability between big- and
9272 little-endian machines, this must be explicitly programmed. This capability
9273 is not provided by @code{Bit_Order}.
9275 @item Components that are positioned across byte boundaries
9277 but do not occupy an integral number of bytes. Given that bytes are not
9278 reordered, such fields would occupy a non-contiguous sequence of bits
9279 in memory, requiring non-trivial code to reassemble. They are for this
9280 reason not permitted, and any component clause specifying such a layout
9281 will be flagged as illegal by GNAT@.
9286 Since the misconception that Bit_Order automatically deals with all
9287 endian-related incompatibilities is a common one, the specification of
9288 a component field that is an integral number of bytes will always
9289 generate a warning. This warning may be suppressed using
9290 @code{pragma Suppress} if desired. The following section contains additional
9291 details regarding the issue of byte ordering.
9293 @node Effect of Bit_Order on Byte Ordering
9294 @section Effect of Bit_Order on Byte Ordering
9295 @cindex byte ordering
9296 @cindex ordering, of bytes
9299 In this section we will review the effect of the @code{Bit_Order} attribute
9300 definition clause on byte ordering. Briefly, it has no effect at all, but
9301 a detailed example will be helpful. Before giving this
9302 example, let us review the precise
9303 definition of the effect of defining @code{Bit_Order}. The effect of a
9304 non-standard bit order is described in section 15.5.3 of the Ada
9308 2 A bit ordering is a method of interpreting the meaning of
9309 the storage place attributes.
9313 To understand the precise definition of storage place attributes in
9314 this context, we visit section 13.5.1 of the manual:
9317 13 A record_representation_clause (without the mod_clause)
9318 specifies the layout. The storage place attributes (see 13.5.2)
9319 are taken from the values of the position, first_bit, and last_bit
9320 expressions after normalizing those values so that first_bit is
9321 less than Storage_Unit.
9325 The critical point here is that storage places are taken from
9326 the values after normalization, not before. So the @code{Bit_Order}
9327 interpretation applies to normalized values. The interpretation
9328 is described in the later part of the 15.5.3 paragraph:
9331 2 A bit ordering is a method of interpreting the meaning of
9332 the storage place attributes. High_Order_First (known in the
9333 vernacular as ``big endian'') means that the first bit of a
9334 storage element (bit 0) is the most significant bit (interpreting
9335 the sequence of bits that represent a component as an unsigned
9336 integer value). Low_Order_First (known in the vernacular as
9337 ``little endian'') means the opposite: the first bit is the
9342 Note that the numbering is with respect to the bits of a storage
9343 unit. In other words, the specification affects only the numbering
9344 of bits within a single storage unit.
9346 We can make the effect clearer by giving an example.
9348 Suppose that we have an external device which presents two bytes, the first
9349 byte presented, which is the first (low addressed byte) of the two byte
9350 record is called Master, and the second byte is called Slave.
9352 The left most (most significant bit is called Control for each byte, and
9353 the remaining 7 bits are called V1, V2, @dots{} V7, where V7 is the rightmost
9354 (least significant) bit.
9356 On a big-endian machine, we can write the following representation clause
9358 @smallexample @c ada
9360 Master_Control : Bit;
9368 Slave_Control : Bit;
9379 Master_Control at 0 range 0 .. 0;
9380 Master_V1 at 0 range 1 .. 1;
9381 Master_V2 at 0 range 2 .. 2;
9382 Master_V3 at 0 range 3 .. 3;
9383 Master_V4 at 0 range 4 .. 4;
9384 Master_V5 at 0 range 5 .. 5;
9385 Master_V6 at 0 range 6 .. 6;
9386 Master_V7 at 0 range 7 .. 7;
9387 Slave_Control at 1 range 0 .. 0;
9388 Slave_V1 at 1 range 1 .. 1;
9389 Slave_V2 at 1 range 2 .. 2;
9390 Slave_V3 at 1 range 3 .. 3;
9391 Slave_V4 at 1 range 4 .. 4;
9392 Slave_V5 at 1 range 5 .. 5;
9393 Slave_V6 at 1 range 6 .. 6;
9394 Slave_V7 at 1 range 7 .. 7;
9399 Now if we move this to a little endian machine, then the bit ordering within
9400 the byte is backwards, so we have to rewrite the record rep clause as:
9402 @smallexample @c ada
9404 Master_Control at 0 range 7 .. 7;
9405 Master_V1 at 0 range 6 .. 6;
9406 Master_V2 at 0 range 5 .. 5;
9407 Master_V3 at 0 range 4 .. 4;
9408 Master_V4 at 0 range 3 .. 3;
9409 Master_V5 at 0 range 2 .. 2;
9410 Master_V6 at 0 range 1 .. 1;
9411 Master_V7 at 0 range 0 .. 0;
9412 Slave_Control at 1 range 7 .. 7;
9413 Slave_V1 at 1 range 6 .. 6;
9414 Slave_V2 at 1 range 5 .. 5;
9415 Slave_V3 at 1 range 4 .. 4;
9416 Slave_V4 at 1 range 3 .. 3;
9417 Slave_V5 at 1 range 2 .. 2;
9418 Slave_V6 at 1 range 1 .. 1;
9419 Slave_V7 at 1 range 0 .. 0;
9424 It is a nuisance to have to rewrite the clause, especially if
9425 the code has to be maintained on both machines. However,
9426 this is a case that we can handle with the
9427 @code{Bit_Order} attribute if it is implemented.
9428 Note that the implementation is not required on byte addressed
9429 machines, but it is indeed implemented in GNAT.
9430 This means that we can simply use the
9431 first record clause, together with the declaration
9433 @smallexample @c ada
9434 for Data'Bit_Order use High_Order_First;
9438 and the effect is what is desired, namely the layout is exactly the same,
9439 independent of whether the code is compiled on a big-endian or little-endian
9442 The important point to understand is that byte ordering is not affected.
9443 A @code{Bit_Order} attribute definition never affects which byte a field
9444 ends up in, only where it ends up in that byte.
9445 To make this clear, let us rewrite the record rep clause of the previous
9448 @smallexample @c ada
9449 for Data'Bit_Order use High_Order_First;
9451 Master_Control at 0 range 0 .. 0;
9452 Master_V1 at 0 range 1 .. 1;
9453 Master_V2 at 0 range 2 .. 2;
9454 Master_V3 at 0 range 3 .. 3;
9455 Master_V4 at 0 range 4 .. 4;
9456 Master_V5 at 0 range 5 .. 5;
9457 Master_V6 at 0 range 6 .. 6;
9458 Master_V7 at 0 range 7 .. 7;
9459 Slave_Control at 0 range 8 .. 8;
9460 Slave_V1 at 0 range 9 .. 9;
9461 Slave_V2 at 0 range 10 .. 10;
9462 Slave_V3 at 0 range 11 .. 11;
9463 Slave_V4 at 0 range 12 .. 12;
9464 Slave_V5 at 0 range 13 .. 13;
9465 Slave_V6 at 0 range 14 .. 14;
9466 Slave_V7 at 0 range 15 .. 15;
9471 This is exactly equivalent to saying (a repeat of the first example):
9473 @smallexample @c ada
9474 for Data'Bit_Order use High_Order_First;
9476 Master_Control at 0 range 0 .. 0;
9477 Master_V1 at 0 range 1 .. 1;
9478 Master_V2 at 0 range 2 .. 2;
9479 Master_V3 at 0 range 3 .. 3;
9480 Master_V4 at 0 range 4 .. 4;
9481 Master_V5 at 0 range 5 .. 5;
9482 Master_V6 at 0 range 6 .. 6;
9483 Master_V7 at 0 range 7 .. 7;
9484 Slave_Control at 1 range 0 .. 0;
9485 Slave_V1 at 1 range 1 .. 1;
9486 Slave_V2 at 1 range 2 .. 2;
9487 Slave_V3 at 1 range 3 .. 3;
9488 Slave_V4 at 1 range 4 .. 4;
9489 Slave_V5 at 1 range 5 .. 5;
9490 Slave_V6 at 1 range 6 .. 6;
9491 Slave_V7 at 1 range 7 .. 7;
9496 Why are they equivalent? Well take a specific field, the @code{Slave_V2}
9497 field. The storage place attributes are obtained by normalizing the
9498 values given so that the @code{First_Bit} value is less than 8. After
9499 normalizing the values (0,10,10) we get (1,2,2) which is exactly what
9500 we specified in the other case.
9502 Now one might expect that the @code{Bit_Order} attribute might affect
9503 bit numbering within the entire record component (two bytes in this
9504 case, thus affecting which byte fields end up in), but that is not
9505 the way this feature is defined, it only affects numbering of bits,
9506 not which byte they end up in.
9508 Consequently it never makes sense to specify a starting bit number
9509 greater than 7 (for a byte addressable field) if an attribute
9510 definition for @code{Bit_Order} has been given, and indeed it
9511 may be actively confusing to specify such a value, so the compiler
9512 generates a warning for such usage.
9514 If you do need to control byte ordering then appropriate conditional
9515 values must be used. If in our example, the slave byte came first on
9516 some machines we might write:
9518 @smallexample @c ada
9519 Master_Byte_First constant Boolean := @dots{};
9521 Master_Byte : constant Natural :=
9522 1 - Boolean'Pos (Master_Byte_First);
9523 Slave_Byte : constant Natural :=
9524 Boolean'Pos (Master_Byte_First);
9526 for Data'Bit_Order use High_Order_First;
9528 Master_Control at Master_Byte range 0 .. 0;
9529 Master_V1 at Master_Byte range 1 .. 1;
9530 Master_V2 at Master_Byte range 2 .. 2;
9531 Master_V3 at Master_Byte range 3 .. 3;
9532 Master_V4 at Master_Byte range 4 .. 4;
9533 Master_V5 at Master_Byte range 5 .. 5;
9534 Master_V6 at Master_Byte range 6 .. 6;
9535 Master_V7 at Master_Byte range 7 .. 7;
9536 Slave_Control at Slave_Byte range 0 .. 0;
9537 Slave_V1 at Slave_Byte range 1 .. 1;
9538 Slave_V2 at Slave_Byte range 2 .. 2;
9539 Slave_V3 at Slave_Byte range 3 .. 3;
9540 Slave_V4 at Slave_Byte range 4 .. 4;
9541 Slave_V5 at Slave_Byte range 5 .. 5;
9542 Slave_V6 at Slave_Byte range 6 .. 6;
9543 Slave_V7 at Slave_Byte range 7 .. 7;
9548 Now to switch between machines, all that is necessary is
9549 to set the boolean constant @code{Master_Byte_First} in
9550 an appropriate manner.
9552 @node Pragma Pack for Arrays
9553 @section Pragma Pack for Arrays
9554 @cindex Pragma Pack (for arrays)
9557 Pragma @code{Pack} applied to an array has no effect unless the component type
9558 is packable. For a component type to be packable, it must be one of the
9565 Any type whose size is specified with a size clause
9567 Any packed array type with a static size
9571 For all these cases, if the component subtype size is in the range
9572 1 through 63, then the effect of the pragma @code{Pack} is exactly as though a
9573 component size were specified giving the component subtype size.
9574 For example if we have:
9576 @smallexample @c ada
9577 type r is range 0 .. 17;
9579 type ar is array (1 .. 8) of r;
9584 Then the component size of @code{ar} will be set to 5 (i.e.@: to @code{r'size},
9585 and the size of the array @code{ar} will be exactly 40 bits.
9587 Note that in some cases this rather fierce approach to packing can produce
9588 unexpected effects. For example, in Ada 95, type Natural typically has a
9589 size of 31, meaning that if you pack an array of Natural, you get 31-bit
9590 close packing, which saves a few bits, but results in far less efficient
9591 access. Since many other Ada compilers will ignore such a packing request,
9592 GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses
9593 might not be what is intended. You can easily remove this warning by
9594 using an explicit @code{Component_Size} setting instead, which never generates
9595 a warning, since the intention of the programmer is clear in this case.
9597 GNAT treats packed arrays in one of two ways. If the size of the array is
9598 known at compile time and is less than 64 bits, then internally the array
9599 is represented as a single modular type, of exactly the appropriate number
9600 of bits. If the length is greater than 63 bits, or is not known at compile
9601 time, then the packed array is represented as an array of bytes, and the
9602 length is always a multiple of 8 bits.
9604 Note that to represent a packed array as a modular type, the alignment must
9605 be suitable for the modular type involved. For example, on typical machines
9606 a 32-bit packed array will be represented by a 32-bit modular integer with
9607 an alignment of four bytes. If you explicitly override the default alignment
9608 with an alignment clause that is too small, the modular representation
9609 cannot be used. For example, consider the following set of declarations:
9611 @smallexample @c ada
9612 type R is range 1 .. 3;
9613 type S is array (1 .. 31) of R;
9614 for S'Component_Size use 2;
9616 for S'Alignment use 1;
9620 If the alignment clause were not present, then a 62-bit modular
9621 representation would be chosen (typically with an alignment of 4 or 8
9622 bytes depending on the target). But the default alignment is overridden
9623 with the explicit alignment clause. This means that the modular
9624 representation cannot be used, and instead the array of bytes
9625 representation must be used, meaning that the length must be a multiple
9626 of 8. Thus the above set of declarations will result in a diagnostic
9627 rejecting the size clause and noting that the minimum size allowed is 64.
9629 @cindex Pragma Pack (for type Natural)
9630 @cindex Pragma Pack warning
9632 One special case that is worth noting occurs when the base type of the
9633 component size is 8/16/32 and the subtype is one bit less. Notably this
9634 occurs with subtype @code{Natural}. Consider:
9636 @smallexample @c ada
9637 type Arr is array (1 .. 32) of Natural;
9642 In all commonly used Ada 83 compilers, this pragma Pack would be ignored,
9643 since typically @code{Natural'Size} is 32 in Ada 83, and in any case most
9644 Ada 83 compilers did not attempt 31 bit packing.
9646 In Ada 95, @code{Natural'Size} is required to be 31. Furthermore, GNAT really
9647 does pack 31-bit subtype to 31 bits. This may result in a substantial
9648 unintended performance penalty when porting legacy Ada 83 code. To help
9649 prevent this, GNAT generates a warning in such cases. If you really want 31
9650 bit packing in a case like this, you can set the component size explicitly:
9652 @smallexample @c ada
9653 type Arr is array (1 .. 32) of Natural;
9654 for Arr'Component_Size use 31;
9658 Here 31-bit packing is achieved as required, and no warning is generated,
9659 since in this case the programmer intention is clear.
9661 @node Pragma Pack for Records
9662 @section Pragma Pack for Records
9663 @cindex Pragma Pack (for records)
9666 Pragma @code{Pack} applied to a record will pack the components to reduce
9667 wasted space from alignment gaps and by reducing the amount of space
9668 taken by components. We distinguish between @emph{packable} components and
9669 @emph{non-packable} components.
9670 Components of the following types are considered packable:
9673 All primitive types are packable.
9676 Small packed arrays, whose size does not exceed 64 bits, and where the
9677 size is statically known at compile time, are represented internally
9678 as modular integers, and so they are also packable.
9683 All packable components occupy the exact number of bits corresponding to
9684 their @code{Size} value, and are packed with no padding bits, i.e.@: they
9685 can start on an arbitrary bit boundary.
9687 All other types are non-packable, they occupy an integral number of
9689 are placed at a boundary corresponding to their alignment requirements.
9691 For example, consider the record
9693 @smallexample @c ada
9694 type Rb1 is array (1 .. 13) of Boolean;
9697 type Rb2 is array (1 .. 65) of Boolean;
9712 The representation for the record x2 is as follows:
9714 @smallexample @c ada
9715 for x2'Size use 224;
9717 l1 at 0 range 0 .. 0;
9718 l2 at 0 range 1 .. 64;
9719 l3 at 12 range 0 .. 31;
9720 l4 at 16 range 0 .. 0;
9721 l5 at 16 range 1 .. 13;
9722 l6 at 18 range 0 .. 71;
9727 Studying this example, we see that the packable fields @code{l1}
9729 of length equal to their sizes, and placed at specific bit boundaries (and
9730 not byte boundaries) to
9731 eliminate padding. But @code{l3} is of a non-packable float type, so
9732 it is on the next appropriate alignment boundary.
9734 The next two fields are fully packable, so @code{l4} and @code{l5} are
9735 minimally packed with no gaps. However, type @code{Rb2} is a packed
9736 array that is longer than 64 bits, so it is itself non-packable. Thus
9737 the @code{l6} field is aligned to the next byte boundary, and takes an
9738 integral number of bytes, i.e.@: 72 bits.
9740 @node Record Representation Clauses
9741 @section Record Representation Clauses
9742 @cindex Record Representation Clause
9745 Record representation clauses may be given for all record types, including
9746 types obtained by record extension. Component clauses are allowed for any
9747 static component. The restrictions on component clauses depend on the type
9750 @cindex Component Clause
9751 For all components of an elementary type, the only restriction on component
9752 clauses is that the size must be at least the 'Size value of the type
9753 (actually the Value_Size). There are no restrictions due to alignment,
9754 and such components may freely cross storage boundaries.
9756 Packed arrays with a size up to and including 64 bits are represented
9757 internally using a modular type with the appropriate number of bits, and
9758 thus the same lack of restriction applies. For example, if you declare:
9760 @smallexample @c ada
9761 type R is array (1 .. 49) of Boolean;
9767 then a component clause for a component of type R may start on any
9768 specified bit boundary, and may specify a value of 49 bits or greater.
9770 For packed bit arrays that are longer than 64 bits, there are two
9771 cases. If the component size is a power of 2 (1,2,4,8,16,32 bits),
9772 including the important case of single bits or boolean values, then
9773 there are no limitations on placement of such components, and they
9774 may start and end at arbitrary bit boundaries.
9776 If the component size is not a power of 2 (e.g. 3 or 5), then
9777 an array of this type longer than 64 bits must always be placed on
9778 on a storage unit (byte) boundary and occupy an integral number
9779 of storage units (bytes). Any component clause that does not
9780 meet this requirement will be rejected.
9782 Any aliased component, or component of an aliased type, must
9783 have its normal alignment and size. A component clause that
9784 does not meet this requirement will be rejected.
9786 The tag field of a tagged type always occupies an address sized field at
9787 the start of the record. No component clause may attempt to overlay this
9788 tag. When a tagged type appears as a component, the tag field must have
9791 In the case of a record extension T1, of a type T, no component clause applied
9792 to the type T1 can specify a storage location that would overlap the first
9793 T'Size bytes of the record.
9795 For all other component types, including non-bit-packed arrays,
9796 the component can be placed at an arbitrary bit boundary,
9797 so for example, the following is permitted:
9799 @smallexample @c ada
9800 type R is array (1 .. 10) of Boolean;
9809 G at 0 range 0 .. 0;
9810 H at 0 range 1 .. 1;
9811 L at 0 range 2 .. 81;
9812 R at 0 range 82 .. 161;
9817 Note: the above rules apply to recent releases of GNAT 5.
9818 In GNAT 3, there are more severe restrictions on larger components.
9819 For non-primitive types, including packed arrays with a size greater than
9820 64 bits, component clauses must respect the alignment requirement of the
9821 type, in particular, always starting on a byte boundary, and the length
9822 must be a multiple of the storage unit.
9824 @node Enumeration Clauses
9825 @section Enumeration Clauses
9827 The only restriction on enumeration clauses is that the range of values
9828 must be representable. For the signed case, if one or more of the
9829 representation values are negative, all values must be in the range:
9831 @smallexample @c ada
9832 System.Min_Int .. System.Max_Int
9836 For the unsigned case, where all values are non negative, the values must
9839 @smallexample @c ada
9840 0 .. System.Max_Binary_Modulus;
9844 A @emph{confirming} representation clause is one in which the values range
9845 from 0 in sequence, i.e.@: a clause that confirms the default representation
9846 for an enumeration type.
9847 Such a confirming representation
9848 is permitted by these rules, and is specially recognized by the compiler so
9849 that no extra overhead results from the use of such a clause.
9851 If an array has an index type which is an enumeration type to which an
9852 enumeration clause has been applied, then the array is stored in a compact
9853 manner. Consider the declarations:
9855 @smallexample @c ada
9856 type r is (A, B, C);
9857 for r use (A => 1, B => 5, C => 10);
9858 type t is array (r) of Character;
9862 The array type t corresponds to a vector with exactly three elements and
9863 has a default size equal to @code{3*Character'Size}. This ensures efficient
9864 use of space, but means that accesses to elements of the array will incur
9865 the overhead of converting representation values to the corresponding
9866 positional values, (i.e.@: the value delivered by the @code{Pos} attribute).
9868 @node Address Clauses
9869 @section Address Clauses
9870 @cindex Address Clause
9872 The reference manual allows a general restriction on representation clauses,
9873 as found in RM 13.1(22):
9876 An implementation need not support representation
9877 items containing nonstatic expressions, except that
9878 an implementation should support a representation item
9879 for a given entity if each nonstatic expression in the
9880 representation item is a name that statically denotes
9881 a constant declared before the entity.
9885 In practice this is applicable only to address clauses, since this is the
9886 only case in which a non-static expression is permitted by the syntax. As
9887 the AARM notes in sections 13.1 (22.a-22.h):
9890 22.a Reason: This is to avoid the following sort of thing:
9892 22.b X : Integer := F(@dots{});
9893 Y : Address := G(@dots{});
9894 for X'Address use Y;
9896 22.c In the above, we have to evaluate the
9897 initialization expression for X before we
9898 know where to put the result. This seems
9899 like an unreasonable implementation burden.
9901 22.d The above code should instead be written
9904 22.e Y : constant Address := G(@dots{});
9905 X : Integer := F(@dots{});
9906 for X'Address use Y;
9908 22.f This allows the expression ``Y'' to be safely
9909 evaluated before X is created.
9911 22.g The constant could be a formal parameter of mode in.
9913 22.h An implementation can support other nonstatic
9914 expressions if it wants to. Expressions of type
9915 Address are hardly ever static, but their value
9916 might be known at compile time anyway in many
9921 GNAT does indeed permit many additional cases of non-static expressions. In
9922 particular, if the type involved is elementary there are no restrictions
9923 (since in this case, holding a temporary copy of the initialization value,
9924 if one is present, is inexpensive). In addition, if there is no implicit or
9925 explicit initialization, then there are no restrictions. GNAT will reject
9926 only the case where all three of these conditions hold:
9931 The type of the item is non-elementary (e.g.@: a record or array).
9934 There is explicit or implicit initialization required for the object.
9935 Note that access values are always implicitly initialized, and also
9936 in GNAT, certain bit-packed arrays (those having a dynamic length or
9937 a length greater than 64) will also be implicitly initialized to zero.
9940 The address value is non-static. Here GNAT is more permissive than the
9941 RM, and allows the address value to be the address of a previously declared
9942 stand-alone variable, as long as it does not itself have an address clause.
9944 @smallexample @c ada
9945 Anchor : Some_Initialized_Type;
9946 Overlay : Some_Initialized_Type;
9947 for Overlay'Address use Anchor'Address;
9951 However, the prefix of the address clause cannot be an array component, or
9952 a component of a discriminated record.
9957 As noted above in section 22.h, address values are typically non-static. In
9958 particular the To_Address function, even if applied to a literal value, is
9959 a non-static function call. To avoid this minor annoyance, GNAT provides
9960 the implementation defined attribute 'To_Address. The following two
9961 expressions have identical values:
9965 @smallexample @c ada
9966 To_Address (16#1234_0000#)
9967 System'To_Address (16#1234_0000#);
9971 except that the second form is considered to be a static expression, and
9972 thus when used as an address clause value is always permitted.
9975 Additionally, GNAT treats as static an address clause that is an
9976 unchecked_conversion of a static integer value. This simplifies the porting
9977 of legacy code, and provides a portable equivalent to the GNAT attribute
9980 Another issue with address clauses is the interaction with alignment
9981 requirements. When an address clause is given for an object, the address
9982 value must be consistent with the alignment of the object (which is usually
9983 the same as the alignment of the type of the object). If an address clause
9984 is given that specifies an inappropriately aligned address value, then the
9985 program execution is erroneous.
9987 Since this source of erroneous behavior can have unfortunate effects, GNAT
9988 checks (at compile time if possible, generating a warning, or at execution
9989 time with a run-time check) that the alignment is appropriate. If the
9990 run-time check fails, then @code{Program_Error} is raised. This run-time
9991 check is suppressed if range checks are suppressed, or if
9992 @code{pragma Restrictions (No_Elaboration_Code)} is in effect.
9995 An address clause cannot be given for an exported object. More
9996 understandably the real restriction is that objects with an address
9997 clause cannot be exported. This is because such variables are not
9998 defined by the Ada program, so there is no external object to export.
10001 It is permissible to give an address clause and a pragma Import for the
10002 same object. In this case, the variable is not really defined by the
10003 Ada program, so there is no external symbol to be linked. The link name
10004 and the external name are ignored in this case. The reason that we allow this
10005 combination is that it provides a useful idiom to avoid unwanted
10006 initializations on objects with address clauses.
10008 When an address clause is given for an object that has implicit or
10009 explicit initialization, then by default initialization takes place. This
10010 means that the effect of the object declaration is to overwrite the
10011 memory at the specified address. This is almost always not what the
10012 programmer wants, so GNAT will output a warning:
10022 for Ext'Address use System'To_Address (16#1234_1234#);
10024 >>> warning: implicit initialization of "Ext" may
10025 modify overlaid storage
10026 >>> warning: use pragma Import for "Ext" to suppress
10027 initialization (RM B(24))
10033 As indicated by the warning message, the solution is to use a (dummy) pragma
10034 Import to suppress this initialization. The pragma tell the compiler that the
10035 object is declared and initialized elsewhere. The following package compiles
10036 without warnings (and the initialization is suppressed):
10038 @smallexample @c ada
10046 for Ext'Address use System'To_Address (16#1234_1234#);
10047 pragma Import (Ada, Ext);
10052 A final issue with address clauses involves their use for overlaying
10053 variables, as in the following example:
10054 @cindex Overlaying of objects
10056 @smallexample @c ada
10059 for B'Address use A'Address;
10063 or alternatively, using the form recommended by the RM:
10065 @smallexample @c ada
10067 Addr : constant Address := A'Address;
10069 for B'Address use Addr;
10073 In both of these cases, @code{A}
10074 and @code{B} become aliased to one another via the
10075 address clause. This use of address clauses to overlay
10076 variables, achieving an effect similar to unchecked
10077 conversion was erroneous in Ada 83, but in Ada 95
10078 the effect is implementation defined. Furthermore, the
10079 Ada 95 RM specifically recommends that in a situation
10080 like this, @code{B} should be subject to the following
10081 implementation advice (RM 13.3(19)):
10084 19 If the Address of an object is specified, or it is imported
10085 or exported, then the implementation should not perform
10086 optimizations based on assumptions of no aliases.
10090 GNAT follows this recommendation, and goes further by also applying
10091 this recommendation to the overlaid variable (@code{A}
10092 in the above example) in this case. This means that the overlay
10093 works "as expected", in that a modification to one of the variables
10094 will affect the value of the other.
10096 @node Effect of Convention on Representation
10097 @section Effect of Convention on Representation
10098 @cindex Convention, effect on representation
10101 Normally the specification of a foreign language convention for a type or
10102 an object has no effect on the chosen representation. In particular, the
10103 representation chosen for data in GNAT generally meets the standard system
10104 conventions, and for example records are laid out in a manner that is
10105 consistent with C@. This means that specifying convention C (for example)
10108 There are three exceptions to this general rule:
10112 @item Convention Fortran and array subtypes
10113 If pragma Convention Fortran is specified for an array subtype, then in
10114 accordance with the implementation advice in section 3.6.2(11) of the
10115 Ada Reference Manual, the array will be stored in a Fortran-compatible
10116 column-major manner, instead of the normal default row-major order.
10118 @item Convention C and enumeration types
10119 GNAT normally stores enumeration types in 8, 16, or 32 bits as required
10120 to accommodate all values of the type. For example, for the enumeration
10123 @smallexample @c ada
10124 type Color is (Red, Green, Blue);
10128 8 bits is sufficient to store all values of the type, so by default, objects
10129 of type @code{Color} will be represented using 8 bits. However, normal C
10130 convention is to use 32 bits for all enum values in C, since enum values
10131 are essentially of type int. If pragma @code{Convention C} is specified for an
10132 Ada enumeration type, then the size is modified as necessary (usually to
10133 32 bits) to be consistent with the C convention for enum values.
10135 @item Convention C/Fortran and Boolean types
10136 In C, the usual convention for boolean values, that is values used for
10137 conditions, is that zero represents false, and nonzero values represent
10138 true. In Ada, the normal convention is that two specific values, typically
10139 0/1, are used to represent false/true respectively.
10141 Fortran has a similar convention for @code{LOGICAL} values (any nonzero
10142 value represents true).
10144 To accommodate the Fortran and C conventions, if a pragma Convention specifies
10145 C or Fortran convention for a derived Boolean, as in the following example:
10147 @smallexample @c ada
10148 type C_Switch is new Boolean;
10149 pragma Convention (C, C_Switch);
10153 then the GNAT generated code will treat any nonzero value as true. For truth
10154 values generated by GNAT, the conventional value 1 will be used for True, but
10155 when one of these values is read, any nonzero value is treated as True.
10159 @node Determining the Representations chosen by GNAT
10160 @section Determining the Representations chosen by GNAT
10161 @cindex Representation, determination of
10162 @cindex @code{-gnatR} switch
10165 Although the descriptions in this section are intended to be complete, it is
10166 often easier to simply experiment to see what GNAT accepts and what the
10167 effect is on the layout of types and objects.
10169 As required by the Ada RM, if a representation clause is not accepted, then
10170 it must be rejected as illegal by the compiler. However, when a
10171 representation clause or pragma is accepted, there can still be questions
10172 of what the compiler actually does. For example, if a partial record
10173 representation clause specifies the location of some components and not
10174 others, then where are the non-specified components placed? Or if pragma
10175 @code{Pack} is used on a record, then exactly where are the resulting
10176 fields placed? The section on pragma @code{Pack} in this chapter can be
10177 used to answer the second question, but it is often easier to just see
10178 what the compiler does.
10180 For this purpose, GNAT provides the option @code{-gnatR}. If you compile
10181 with this option, then the compiler will output information on the actual
10182 representations chosen, in a format similar to source representation
10183 clauses. For example, if we compile the package:
10185 @smallexample @c ada
10187 type r (x : boolean) is tagged record
10189 when True => S : String (1 .. 100);
10190 when False => null;
10194 type r2 is new r (false) with record
10199 y2 at 16 range 0 .. 31;
10206 type x1 is array (1 .. 10) of x;
10207 for x1'component_size use 11;
10209 type ia is access integer;
10211 type Rb1 is array (1 .. 13) of Boolean;
10214 type Rb2 is array (1 .. 65) of Boolean;
10230 using the switch @code{-gnatR} we obtain the following output:
10233 Representation information for unit q
10234 -------------------------------------
10237 for r'Alignment use 4;
10239 x at 4 range 0 .. 7;
10240 _tag at 0 range 0 .. 31;
10241 s at 5 range 0 .. 799;
10244 for r2'Size use 160;
10245 for r2'Alignment use 4;
10247 x at 4 range 0 .. 7;
10248 _tag at 0 range 0 .. 31;
10249 _parent at 0 range 0 .. 63;
10250 y2 at 16 range 0 .. 31;
10254 for x'Alignment use 1;
10256 y at 0 range 0 .. 7;
10259 for x1'Size use 112;
10260 for x1'Alignment use 1;
10261 for x1'Component_Size use 11;
10263 for rb1'Size use 13;
10264 for rb1'Alignment use 2;
10265 for rb1'Component_Size use 1;
10267 for rb2'Size use 72;
10268 for rb2'Alignment use 1;
10269 for rb2'Component_Size use 1;
10271 for x2'Size use 224;
10272 for x2'Alignment use 4;
10274 l1 at 0 range 0 .. 0;
10275 l2 at 0 range 1 .. 64;
10276 l3 at 12 range 0 .. 31;
10277 l4 at 16 range 0 .. 0;
10278 l5 at 16 range 1 .. 13;
10279 l6 at 18 range 0 .. 71;
10284 The Size values are actually the Object_Size, i.e.@: the default size that
10285 will be allocated for objects of the type.
10286 The ?? size for type r indicates that we have a variant record, and the
10287 actual size of objects will depend on the discriminant value.
10289 The Alignment values show the actual alignment chosen by the compiler
10290 for each record or array type.
10292 The record representation clause for type r shows where all fields
10293 are placed, including the compiler generated tag field (whose location
10294 cannot be controlled by the programmer).
10296 The record representation clause for the type extension r2 shows all the
10297 fields present, including the parent field, which is a copy of the fields
10298 of the parent type of r2, i.e.@: r1.
10300 The component size and size clauses for types rb1 and rb2 show
10301 the exact effect of pragma @code{Pack} on these arrays, and the record
10302 representation clause for type x2 shows how pragma @code{Pack} affects
10305 In some cases, it may be useful to cut and paste the representation clauses
10306 generated by the compiler into the original source to fix and guarantee
10307 the actual representation to be used.
10309 @node Standard Library Routines
10310 @chapter Standard Library Routines
10313 The Ada 95 Reference Manual contains in Annex A a full description of an
10314 extensive set of standard library routines that can be used in any Ada
10315 program, and which must be provided by all Ada compilers. They are
10316 analogous to the standard C library used by C programs.
10318 GNAT implements all of the facilities described in annex A, and for most
10319 purposes the description in the Ada 95
10320 reference manual, or appropriate Ada
10321 text book, will be sufficient for making use of these facilities.
10323 In the case of the input-output facilities, @xref{The Implementation of
10324 Standard I/O}, gives details on exactly how GNAT interfaces to the
10325 file system. For the remaining packages, the Ada 95 reference manual
10326 should be sufficient. The following is a list of the packages included,
10327 together with a brief description of the functionality that is provided.
10329 For completeness, references are included to other predefined library
10330 routines defined in other sections of the Ada 95 reference manual (these are
10331 cross-indexed from annex A).
10335 This is a parent package for all the standard library packages. It is
10336 usually included implicitly in your program, and itself contains no
10337 useful data or routines.
10339 @item Ada.Calendar (9.6)
10340 @code{Calendar} provides time of day access, and routines for
10341 manipulating times and durations.
10343 @item Ada.Characters (A.3.1)
10344 This is a dummy parent package that contains no useful entities
10346 @item Ada.Characters.Handling (A.3.2)
10347 This package provides some basic character handling capabilities,
10348 including classification functions for classes of characters (e.g.@: test
10349 for letters, or digits).
10351 @item Ada.Characters.Latin_1 (A.3.3)
10352 This package includes a complete set of definitions of the characters
10353 that appear in type CHARACTER@. It is useful for writing programs that
10354 will run in international environments. For example, if you want an
10355 upper case E with an acute accent in a string, it is often better to use
10356 the definition of @code{UC_E_Acute} in this package. Then your program
10357 will print in an understandable manner even if your environment does not
10358 support these extended characters.
10360 @item Ada.Command_Line (A.15)
10361 This package provides access to the command line parameters and the name
10362 of the current program (analogous to the use of @code{argc} and @code{argv}
10363 in C), and also allows the exit status for the program to be set in a
10364 system-independent manner.
10366 @item Ada.Decimal (F.2)
10367 This package provides constants describing the range of decimal numbers
10368 implemented, and also a decimal divide routine (analogous to the COBOL
10369 verb DIVIDE .. GIVING .. REMAINDER ..)
10371 @item Ada.Direct_IO (A.8.4)
10372 This package provides input-output using a model of a set of records of
10373 fixed-length, containing an arbitrary definite Ada type, indexed by an
10374 integer record number.
10376 @item Ada.Dynamic_Priorities (D.5)
10377 This package allows the priorities of a task to be adjusted dynamically
10378 as the task is running.
10380 @item Ada.Exceptions (11.4.1)
10381 This package provides additional information on exceptions, and also
10382 contains facilities for treating exceptions as data objects, and raising
10383 exceptions with associated messages.
10385 @item Ada.Finalization (7.6)
10386 This package contains the declarations and subprograms to support the
10387 use of controlled types, providing for automatic initialization and
10388 finalization (analogous to the constructors and destructors of C++)
10390 @item Ada.Interrupts (C.3.2)
10391 This package provides facilities for interfacing to interrupts, which
10392 includes the set of signals or conditions that can be raised and
10393 recognized as interrupts.
10395 @item Ada.Interrupts.Names (C.3.2)
10396 This package provides the set of interrupt names (actually signal
10397 or condition names) that can be handled by GNAT@.
10399 @item Ada.IO_Exceptions (A.13)
10400 This package defines the set of exceptions that can be raised by use of
10401 the standard IO packages.
10404 This package contains some standard constants and exceptions used
10405 throughout the numerics packages. Note that the constants pi and e are
10406 defined here, and it is better to use these definitions than rolling
10409 @item Ada.Numerics.Complex_Elementary_Functions
10410 Provides the implementation of standard elementary functions (such as
10411 log and trigonometric functions) operating on complex numbers using the
10412 standard @code{Float} and the @code{Complex} and @code{Imaginary} types
10413 created by the package @code{Numerics.Complex_Types}.
10415 @item Ada.Numerics.Complex_Types
10416 This is a predefined instantiation of
10417 @code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to
10418 build the type @code{Complex} and @code{Imaginary}.
10420 @item Ada.Numerics.Discrete_Random
10421 This package provides a random number generator suitable for generating
10422 random integer values from a specified range.
10424 @item Ada.Numerics.Float_Random
10425 This package provides a random number generator suitable for generating
10426 uniformly distributed floating point values.
10428 @item Ada.Numerics.Generic_Complex_Elementary_Functions
10429 This is a generic version of the package that provides the
10430 implementation of standard elementary functions (such as log and
10431 trigonometric functions) for an arbitrary complex type.
10433 The following predefined instantiations of this package are provided:
10437 @code{Ada.Numerics.Short_Complex_Elementary_Functions}
10439 @code{Ada.Numerics.Complex_Elementary_Functions}
10441 @code{Ada.Numerics.
10442 Long_Complex_Elementary_Functions}
10445 @item Ada.Numerics.Generic_Complex_Types
10446 This is a generic package that allows the creation of complex types,
10447 with associated complex arithmetic operations.
10449 The following predefined instantiations of this package exist
10452 @code{Ada.Numerics.Short_Complex_Complex_Types}
10454 @code{Ada.Numerics.Complex_Complex_Types}
10456 @code{Ada.Numerics.Long_Complex_Complex_Types}
10459 @item Ada.Numerics.Generic_Elementary_Functions
10460 This is a generic package that provides the implementation of standard
10461 elementary functions (such as log an trigonometric functions) for an
10462 arbitrary float type.
10464 The following predefined instantiations of this package exist
10468 @code{Ada.Numerics.Short_Elementary_Functions}
10470 @code{Ada.Numerics.Elementary_Functions}
10472 @code{Ada.Numerics.Long_Elementary_Functions}
10475 @item Ada.Real_Time (D.8)
10476 This package provides facilities similar to those of @code{Calendar}, but
10477 operating with a finer clock suitable for real time control. Note that
10478 annex D requires that there be no backward clock jumps, and GNAT generally
10479 guarantees this behavior, but of course if the external clock on which
10480 the GNAT runtime depends is deliberately reset by some external event,
10481 then such a backward jump may occur.
10483 @item Ada.Sequential_IO (A.8.1)
10484 This package provides input-output facilities for sequential files,
10485 which can contain a sequence of values of a single type, which can be
10486 any Ada type, including indefinite (unconstrained) types.
10488 @item Ada.Storage_IO (A.9)
10489 This package provides a facility for mapping arbitrary Ada types to and
10490 from a storage buffer. It is primarily intended for the creation of new
10493 @item Ada.Streams (13.13.1)
10494 This is a generic package that provides the basic support for the
10495 concept of streams as used by the stream attributes (@code{Input},
10496 @code{Output}, @code{Read} and @code{Write}).
10498 @item Ada.Streams.Stream_IO (A.12.1)
10499 This package is a specialization of the type @code{Streams} defined in
10500 package @code{Streams} together with a set of operations providing
10501 Stream_IO capability. The Stream_IO model permits both random and
10502 sequential access to a file which can contain an arbitrary set of values
10503 of one or more Ada types.
10505 @item Ada.Strings (A.4.1)
10506 This package provides some basic constants used by the string handling
10509 @item Ada.Strings.Bounded (A.4.4)
10510 This package provides facilities for handling variable length
10511 strings. The bounded model requires a maximum length. It is thus
10512 somewhat more limited than the unbounded model, but avoids the use of
10513 dynamic allocation or finalization.
10515 @item Ada.Strings.Fixed (A.4.3)
10516 This package provides facilities for handling fixed length strings.
10518 @item Ada.Strings.Maps (A.4.2)
10519 This package provides facilities for handling character mappings and
10520 arbitrarily defined subsets of characters. For instance it is useful in
10521 defining specialized translation tables.
10523 @item Ada.Strings.Maps.Constants (A.4.6)
10524 This package provides a standard set of predefined mappings and
10525 predefined character sets. For example, the standard upper to lower case
10526 conversion table is found in this package. Note that upper to lower case
10527 conversion is non-trivial if you want to take the entire set of
10528 characters, including extended characters like E with an acute accent,
10529 into account. You should use the mappings in this package (rather than
10530 adding 32 yourself) to do case mappings.
10532 @item Ada.Strings.Unbounded (A.4.5)
10533 This package provides facilities for handling variable length
10534 strings. The unbounded model allows arbitrary length strings, but
10535 requires the use of dynamic allocation and finalization.
10537 @item Ada.Strings.Wide_Bounded (A.4.7)
10538 @itemx Ada.Strings.Wide_Fixed (A.4.7)
10539 @itemx Ada.Strings.Wide_Maps (A.4.7)
10540 @itemx Ada.Strings.Wide_Maps.Constants (A.4.7)
10541 @itemx Ada.Strings.Wide_Unbounded (A.4.7)
10542 These packages provide analogous capabilities to the corresponding
10543 packages without @samp{Wide_} in the name, but operate with the types
10544 @code{Wide_String} and @code{Wide_Character} instead of @code{String}
10545 and @code{Character}.
10547 @item Ada.Strings.Wide_Wide_Bounded (A.4.7)
10548 @itemx Ada.Strings.Wide_Wide_Fixed (A.4.7)
10549 @itemx Ada.Strings.Wide_Wide_Maps (A.4.7)
10550 @itemx Ada.Strings.Wide_Wide_Maps.Constants (A.4.7)
10551 @itemx Ada.Strings.Wide_Wide_Unbounded (A.4.7)
10552 These packages provide analogous capabilities to the corresponding
10553 packages without @samp{Wide_} in the name, but operate with the types
10554 @code{Wide_Wide_String} and @code{Wide_Wide_Character} instead
10555 of @code{String} and @code{Character}.
10557 @item Ada.Synchronous_Task_Control (D.10)
10558 This package provides some standard facilities for controlling task
10559 communication in a synchronous manner.
10562 This package contains definitions for manipulation of the tags of tagged
10565 @item Ada.Task_Attributes
10566 This package provides the capability of associating arbitrary
10567 task-specific data with separate tasks.
10570 This package provides basic text input-output capabilities for
10571 character, string and numeric data. The subpackages of this
10572 package are listed next.
10574 @item Ada.Text_IO.Decimal_IO
10575 Provides input-output facilities for decimal fixed-point types
10577 @item Ada.Text_IO.Enumeration_IO
10578 Provides input-output facilities for enumeration types.
10580 @item Ada.Text_IO.Fixed_IO
10581 Provides input-output facilities for ordinary fixed-point types.
10583 @item Ada.Text_IO.Float_IO
10584 Provides input-output facilities for float types. The following
10585 predefined instantiations of this generic package are available:
10589 @code{Short_Float_Text_IO}
10591 @code{Float_Text_IO}
10593 @code{Long_Float_Text_IO}
10596 @item Ada.Text_IO.Integer_IO
10597 Provides input-output facilities for integer types. The following
10598 predefined instantiations of this generic package are available:
10601 @item Short_Short_Integer
10602 @code{Ada.Short_Short_Integer_Text_IO}
10603 @item Short_Integer
10604 @code{Ada.Short_Integer_Text_IO}
10606 @code{Ada.Integer_Text_IO}
10608 @code{Ada.Long_Integer_Text_IO}
10609 @item Long_Long_Integer
10610 @code{Ada.Long_Long_Integer_Text_IO}
10613 @item Ada.Text_IO.Modular_IO
10614 Provides input-output facilities for modular (unsigned) types
10616 @item Ada.Text_IO.Complex_IO (G.1.3)
10617 This package provides basic text input-output capabilities for complex
10620 @item Ada.Text_IO.Editing (F.3.3)
10621 This package contains routines for edited output, analogous to the use
10622 of pictures in COBOL@. The picture formats used by this package are a
10623 close copy of the facility in COBOL@.
10625 @item Ada.Text_IO.Text_Streams (A.12.2)
10626 This package provides a facility that allows Text_IO files to be treated
10627 as streams, so that the stream attributes can be used for writing
10628 arbitrary data, including binary data, to Text_IO files.
10630 @item Ada.Unchecked_Conversion (13.9)
10631 This generic package allows arbitrary conversion from one type to
10632 another of the same size, providing for breaking the type safety in
10633 special circumstances.
10635 If the types have the same Size (more accurately the same Value_Size),
10636 then the effect is simply to transfer the bits from the source to the
10637 target type without any modification. This usage is well defined, and
10638 for simple types whose representation is typically the same across
10639 all implementations, gives a portable method of performing such
10642 If the types do not have the same size, then the result is implementation
10643 defined, and thus may be non-portable. The following describes how GNAT
10644 handles such unchecked conversion cases.
10646 If the types are of different sizes, and are both discrete types, then
10647 the effect is of a normal type conversion without any constraint checking.
10648 In particular if the result type has a larger size, the result will be
10649 zero or sign extended. If the result type has a smaller size, the result
10650 will be truncated by ignoring high order bits.
10652 If the types are of different sizes, and are not both discrete types,
10653 then the conversion works as though pointers were created to the source
10654 and target, and the pointer value is converted. The effect is that bits
10655 are copied from successive low order storage units and bits of the source
10656 up to the length of the target type.
10658 A warning is issued if the lengths differ, since the effect in this
10659 case is implementation dependent, and the above behavior may not match
10660 that of some other compiler.
10662 A pointer to one type may be converted to a pointer to another type using
10663 unchecked conversion. The only case in which the effect is undefined is
10664 when one or both pointers are pointers to unconstrained array types. In
10665 this case, the bounds information may get incorrectly transferred, and in
10666 particular, GNAT uses double size pointers for such types, and it is
10667 meaningless to convert between such pointer types. GNAT will issue a
10668 warning if the alignment of the target designated type is more strict
10669 than the alignment of the source designated type (since the result may
10670 be unaligned in this case).
10672 A pointer other than a pointer to an unconstrained array type may be
10673 converted to and from System.Address. Such usage is common in Ada 83
10674 programs, but note that Ada.Address_To_Access_Conversions is the
10675 preferred method of performing such conversions in Ada 95. Neither
10676 unchecked conversion nor Ada.Address_To_Access_Conversions should be
10677 used in conjunction with pointers to unconstrained objects, since
10678 the bounds information cannot be handled correctly in this case.
10680 @item Ada.Unchecked_Deallocation (13.11.2)
10681 This generic package allows explicit freeing of storage previously
10682 allocated by use of an allocator.
10684 @item Ada.Wide_Text_IO (A.11)
10685 This package is similar to @code{Ada.Text_IO}, except that the external
10686 file supports wide character representations, and the internal types are
10687 @code{Wide_Character} and @code{Wide_String} instead of @code{Character}
10688 and @code{String}. It contains generic subpackages listed next.
10690 @item Ada.Wide_Text_IO.Decimal_IO
10691 Provides input-output facilities for decimal fixed-point types
10693 @item Ada.Wide_Text_IO.Enumeration_IO
10694 Provides input-output facilities for enumeration types.
10696 @item Ada.Wide_Text_IO.Fixed_IO
10697 Provides input-output facilities for ordinary fixed-point types.
10699 @item Ada.Wide_Text_IO.Float_IO
10700 Provides input-output facilities for float types. The following
10701 predefined instantiations of this generic package are available:
10705 @code{Short_Float_Wide_Text_IO}
10707 @code{Float_Wide_Text_IO}
10709 @code{Long_Float_Wide_Text_IO}
10712 @item Ada.Wide_Text_IO.Integer_IO
10713 Provides input-output facilities for integer types. The following
10714 predefined instantiations of this generic package are available:
10717 @item Short_Short_Integer
10718 @code{Ada.Short_Short_Integer_Wide_Text_IO}
10719 @item Short_Integer
10720 @code{Ada.Short_Integer_Wide_Text_IO}
10722 @code{Ada.Integer_Wide_Text_IO}
10724 @code{Ada.Long_Integer_Wide_Text_IO}
10725 @item Long_Long_Integer
10726 @code{Ada.Long_Long_Integer_Wide_Text_IO}
10729 @item Ada.Wide_Text_IO.Modular_IO
10730 Provides input-output facilities for modular (unsigned) types
10732 @item Ada.Wide_Text_IO.Complex_IO (G.1.3)
10733 This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the
10734 external file supports wide character representations.
10736 @item Ada.Wide_Text_IO.Editing (F.3.4)
10737 This package is similar to @code{Ada.Text_IO.Editing}, except that the
10738 types are @code{Wide_Character} and @code{Wide_String} instead of
10739 @code{Character} and @code{String}.
10741 @item Ada.Wide_Text_IO.Streams (A.12.3)
10742 This package is similar to @code{Ada.Text_IO.Streams}, except that the
10743 types are @code{Wide_Character} and @code{Wide_String} instead of
10744 @code{Character} and @code{String}.
10746 @item Ada.Wide_Wide_Text_IO (A.11)
10747 This package is similar to @code{Ada.Text_IO}, except that the external
10748 file supports wide character representations, and the internal types are
10749 @code{Wide_Character} and @code{Wide_String} instead of @code{Character}
10750 and @code{String}. It contains generic subpackages listed next.
10752 @item Ada.Wide_Wide_Text_IO.Decimal_IO
10753 Provides input-output facilities for decimal fixed-point types
10755 @item Ada.Wide_Wide_Text_IO.Enumeration_IO
10756 Provides input-output facilities for enumeration types.
10758 @item Ada.Wide_Wide_Text_IO.Fixed_IO
10759 Provides input-output facilities for ordinary fixed-point types.
10761 @item Ada.Wide_Wide_Text_IO.Float_IO
10762 Provides input-output facilities for float types. The following
10763 predefined instantiations of this generic package are available:
10767 @code{Short_Float_Wide_Wide_Text_IO}
10769 @code{Float_Wide_Wide_Text_IO}
10771 @code{Long_Float_Wide_Wide_Text_IO}
10774 @item Ada.Wide_Wide_Text_IO.Integer_IO
10775 Provides input-output facilities for integer types. The following
10776 predefined instantiations of this generic package are available:
10779 @item Short_Short_Integer
10780 @code{Ada.Short_Short_Integer_Wide_Wide_Text_IO}
10781 @item Short_Integer
10782 @code{Ada.Short_Integer_Wide_Wide_Text_IO}
10784 @code{Ada.Integer_Wide_Wide_Text_IO}
10786 @code{Ada.Long_Integer_Wide_Wide_Text_IO}
10787 @item Long_Long_Integer
10788 @code{Ada.Long_Long_Integer_Wide_Wide_Text_IO}
10791 @item Ada.Wide_Wide_Text_IO.Modular_IO
10792 Provides input-output facilities for modular (unsigned) types
10794 @item Ada.Wide_Wide_Text_IO.Complex_IO (G.1.3)
10795 This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the
10796 external file supports wide character representations.
10798 @item Ada.Wide_Wide_Text_IO.Editing (F.3.4)
10799 This package is similar to @code{Ada.Text_IO.Editing}, except that the
10800 types are @code{Wide_Character} and @code{Wide_String} instead of
10801 @code{Character} and @code{String}.
10803 @item Ada.Wide_Wide_Text_IO.Streams (A.12.3)
10804 This package is similar to @code{Ada.Text_IO.Streams}, except that the
10805 types are @code{Wide_Character} and @code{Wide_String} instead of
10806 @code{Character} and @code{String}.
10811 @node The Implementation of Standard I/O
10812 @chapter The Implementation of Standard I/O
10815 GNAT implements all the required input-output facilities described in
10816 A.6 through A.14. These sections of the Ada 95 reference manual describe the
10817 required behavior of these packages from the Ada point of view, and if
10818 you are writing a portable Ada program that does not need to know the
10819 exact manner in which Ada maps to the outside world when it comes to
10820 reading or writing external files, then you do not need to read this
10821 chapter. As long as your files are all regular files (not pipes or
10822 devices), and as long as you write and read the files only from Ada, the
10823 description in the Ada 95 reference manual is sufficient.
10825 However, if you want to do input-output to pipes or other devices, such
10826 as the keyboard or screen, or if the files you are dealing with are
10827 either generated by some other language, or to be read by some other
10828 language, then you need to know more about the details of how the GNAT
10829 implementation of these input-output facilities behaves.
10831 In this chapter we give a detailed description of exactly how GNAT
10832 interfaces to the file system. As always, the sources of the system are
10833 available to you for answering questions at an even more detailed level,
10834 but for most purposes the information in this chapter will suffice.
10836 Another reason that you may need to know more about how input-output is
10837 implemented arises when you have a program written in mixed languages
10838 where, for example, files are shared between the C and Ada sections of
10839 the same program. GNAT provides some additional facilities, in the form
10840 of additional child library packages, that facilitate this sharing, and
10841 these additional facilities are also described in this chapter.
10844 * Standard I/O Packages::
10850 * Wide_Wide_Text_IO::
10854 * Operations on C Streams::
10855 * Interfacing to C Streams::
10858 @node Standard I/O Packages
10859 @section Standard I/O Packages
10862 The Standard I/O packages described in Annex A for
10868 Ada.Text_IO.Complex_IO
10870 Ada.Text_IO.Text_Streams
10874 Ada.Wide_Text_IO.Complex_IO
10876 Ada.Wide_Text_IO.Text_Streams
10878 Ada.Wide_Wide_Text_IO
10880 Ada.Wide_Wide_Text_IO.Complex_IO
10882 Ada.Wide_Wide_Text_IO.Text_Streams
10892 are implemented using the C
10893 library streams facility; where
10897 All files are opened using @code{fopen}.
10899 All input/output operations use @code{fread}/@code{fwrite}.
10903 There is no internal buffering of any kind at the Ada library level. The
10904 only buffering is that provided at the system level in the
10905 implementation of the C library routines that support streams. This
10906 facilitates shared use of these streams by mixed language programs.
10909 @section FORM Strings
10912 The format of a FORM string in GNAT is:
10915 "keyword=value,keyword=value,@dots{},keyword=value"
10919 where letters may be in upper or lower case, and there are no spaces
10920 between values. The order of the entries is not important. Currently
10921 there are two keywords defined.
10929 The use of these parameters is described later in this section.
10935 Direct_IO can only be instantiated for definite types. This is a
10936 restriction of the Ada language, which means that the records are fixed
10937 length (the length being determined by @code{@var{type}'Size}, rounded
10938 up to the next storage unit boundary if necessary).
10940 The records of a Direct_IO file are simply written to the file in index
10941 sequence, with the first record starting at offset zero, and subsequent
10942 records following. There is no control information of any kind. For
10943 example, if 32-bit integers are being written, each record takes
10944 4-bytes, so the record at index @var{K} starts at offset
10945 (@var{K}@minus{}1)*4.
10947 There is no limit on the size of Direct_IO files, they are expanded as
10948 necessary to accommodate whatever records are written to the file.
10950 @node Sequential_IO
10951 @section Sequential_IO
10954 Sequential_IO may be instantiated with either a definite (constrained)
10955 or indefinite (unconstrained) type.
10957 For the definite type case, the elements written to the file are simply
10958 the memory images of the data values with no control information of any
10959 kind. The resulting file should be read using the same type, no validity
10960 checking is performed on input.
10962 For the indefinite type case, the elements written consist of two
10963 parts. First is the size of the data item, written as the memory image
10964 of a @code{Interfaces.C.size_t} value, followed by the memory image of
10965 the data value. The resulting file can only be read using the same
10966 (unconstrained) type. Normal assignment checks are performed on these
10967 read operations, and if these checks fail, @code{Data_Error} is
10968 raised. In particular, in the array case, the lengths must match, and in
10969 the variant record case, if the variable for a particular read operation
10970 is constrained, the discriminants must match.
10972 Note that it is not possible to use Sequential_IO to write variable
10973 length array items, and then read the data back into different length
10974 arrays. For example, the following will raise @code{Data_Error}:
10976 @smallexample @c ada
10977 package IO is new Sequential_IO (String);
10982 IO.Write (F, "hello!")
10983 IO.Reset (F, Mode=>In_File);
10990 On some Ada implementations, this will print @code{hell}, but the program is
10991 clearly incorrect, since there is only one element in the file, and that
10992 element is the string @code{hello!}.
10994 In Ada 95, this kind of behavior can be legitimately achieved using
10995 Stream_IO, and this is the preferred mechanism. In particular, the above
10996 program fragment rewritten to use Stream_IO will work correctly.
11002 Text_IO files consist of a stream of characters containing the following
11003 special control characters:
11006 LF (line feed, 16#0A#) Line Mark
11007 FF (form feed, 16#0C#) Page Mark
11011 A canonical Text_IO file is defined as one in which the following
11012 conditions are met:
11016 The character @code{LF} is used only as a line mark, i.e.@: to mark the end
11020 The character @code{FF} is used only as a page mark, i.e.@: to mark the
11021 end of a page and consequently can appear only immediately following a
11022 @code{LF} (line mark) character.
11025 The file ends with either @code{LF} (line mark) or @code{LF}-@code{FF}
11026 (line mark, page mark). In the former case, the page mark is implicitly
11027 assumed to be present.
11031 A file written using Text_IO will be in canonical form provided that no
11032 explicit @code{LF} or @code{FF} characters are written using @code{Put}
11033 or @code{Put_Line}. There will be no @code{FF} character at the end of
11034 the file unless an explicit @code{New_Page} operation was performed
11035 before closing the file.
11037 A canonical Text_IO file that is a regular file, i.e.@: not a device or a
11038 pipe, can be read using any of the routines in Text_IO@. The
11039 semantics in this case will be exactly as defined in the Ada 95 reference
11040 manual and all the routines in Text_IO are fully implemented.
11042 A text file that does not meet the requirements for a canonical Text_IO
11043 file has one of the following:
11047 The file contains @code{FF} characters not immediately following a
11048 @code{LF} character.
11051 The file contains @code{LF} or @code{FF} characters written by
11052 @code{Put} or @code{Put_Line}, which are not logically considered to be
11053 line marks or page marks.
11056 The file ends in a character other than @code{LF} or @code{FF},
11057 i.e.@: there is no explicit line mark or page mark at the end of the file.
11061 Text_IO can be used to read such non-standard text files but subprograms
11062 to do with line or page numbers do not have defined meanings. In
11063 particular, a @code{FF} character that does not follow a @code{LF}
11064 character may or may not be treated as a page mark from the point of
11065 view of page and line numbering. Every @code{LF} character is considered
11066 to end a line, and there is an implied @code{LF} character at the end of
11070 * Text_IO Stream Pointer Positioning::
11071 * Text_IO Reading and Writing Non-Regular Files::
11073 * Treating Text_IO Files as Streams::
11074 * Text_IO Extensions::
11075 * Text_IO Facilities for Unbounded Strings::
11078 @node Text_IO Stream Pointer Positioning
11079 @subsection Stream Pointer Positioning
11082 @code{Ada.Text_IO} has a definition of current position for a file that
11083 is being read. No internal buffering occurs in Text_IO, and usually the
11084 physical position in the stream used to implement the file corresponds
11085 to this logical position defined by Text_IO@. There are two exceptions:
11089 After a call to @code{End_Of_Page} that returns @code{True}, the stream
11090 is positioned past the @code{LF} (line mark) that precedes the page
11091 mark. Text_IO maintains an internal flag so that subsequent read
11092 operations properly handle the logical position which is unchanged by
11093 the @code{End_Of_Page} call.
11096 After a call to @code{End_Of_File} that returns @code{True}, if the
11097 Text_IO file was positioned before the line mark at the end of file
11098 before the call, then the logical position is unchanged, but the stream
11099 is physically positioned right at the end of file (past the line mark,
11100 and past a possible page mark following the line mark. Again Text_IO
11101 maintains internal flags so that subsequent read operations properly
11102 handle the logical position.
11106 These discrepancies have no effect on the observable behavior of
11107 Text_IO, but if a single Ada stream is shared between a C program and
11108 Ada program, or shared (using @samp{shared=yes} in the form string)
11109 between two Ada files, then the difference may be observable in some
11112 @node Text_IO Reading and Writing Non-Regular Files
11113 @subsection Reading and Writing Non-Regular Files
11116 A non-regular file is a device (such as a keyboard), or a pipe. Text_IO
11117 can be used for reading and writing. Writing is not affected and the
11118 sequence of characters output is identical to the normal file case, but
11119 for reading, the behavior of Text_IO is modified to avoid undesirable
11120 look-ahead as follows:
11122 An input file that is not a regular file is considered to have no page
11123 marks. Any @code{Ascii.FF} characters (the character normally used for a
11124 page mark) appearing in the file are considered to be data
11125 characters. In particular:
11129 @code{Get_Line} and @code{Skip_Line} do not test for a page mark
11130 following a line mark. If a page mark appears, it will be treated as a
11134 This avoids the need to wait for an extra character to be typed or
11135 entered from the pipe to complete one of these operations.
11138 @code{End_Of_Page} always returns @code{False}
11141 @code{End_Of_File} will return @code{False} if there is a page mark at
11142 the end of the file.
11146 Output to non-regular files is the same as for regular files. Page marks
11147 may be written to non-regular files using @code{New_Page}, but as noted
11148 above they will not be treated as page marks on input if the output is
11149 piped to another Ada program.
11151 Another important discrepancy when reading non-regular files is that the end
11152 of file indication is not ``sticky''. If an end of file is entered, e.g.@: by
11153 pressing the @key{EOT} key,
11155 is signaled once (i.e.@: the test @code{End_Of_File}
11156 will yield @code{True}, or a read will
11157 raise @code{End_Error}), but then reading can resume
11158 to read data past that end of
11159 file indication, until another end of file indication is entered.
11161 @node Get_Immediate
11162 @subsection Get_Immediate
11163 @cindex Get_Immediate
11166 Get_Immediate returns the next character (including control characters)
11167 from the input file. In particular, Get_Immediate will return LF or FF
11168 characters used as line marks or page marks. Such operations leave the
11169 file positioned past the control character, and it is thus not treated
11170 as having its normal function. This means that page, line and column
11171 counts after this kind of Get_Immediate call are set as though the mark
11172 did not occur. In the case where a Get_Immediate leaves the file
11173 positioned between the line mark and page mark (which is not normally
11174 possible), it is undefined whether the FF character will be treated as a
11177 @node Treating Text_IO Files as Streams
11178 @subsection Treating Text_IO Files as Streams
11179 @cindex Stream files
11182 The package @code{Text_IO.Streams} allows a Text_IO file to be treated
11183 as a stream. Data written to a Text_IO file in this stream mode is
11184 binary data. If this binary data contains bytes 16#0A# (@code{LF}) or
11185 16#0C# (@code{FF}), the resulting file may have non-standard
11186 format. Similarly if read operations are used to read from a Text_IO
11187 file treated as a stream, then @code{LF} and @code{FF} characters may be
11188 skipped and the effect is similar to that described above for
11189 @code{Get_Immediate}.
11191 @node Text_IO Extensions
11192 @subsection Text_IO Extensions
11193 @cindex Text_IO extensions
11196 A package GNAT.IO_Aux in the GNAT library provides some useful extensions
11197 to the standard @code{Text_IO} package:
11200 @item function File_Exists (Name : String) return Boolean;
11201 Determines if a file of the given name exists.
11203 @item function Get_Line return String;
11204 Reads a string from the standard input file. The value returned is exactly
11205 the length of the line that was read.
11207 @item function Get_Line (File : Ada.Text_IO.File_Type) return String;
11208 Similar, except that the parameter File specifies the file from which
11209 the string is to be read.
11213 @node Text_IO Facilities for Unbounded Strings
11214 @subsection Text_IO Facilities for Unbounded Strings
11215 @cindex Text_IO for unbounded strings
11216 @cindex Unbounded_String, Text_IO operations
11219 The package @code{Ada.Strings.Unbounded.Text_IO}
11220 in library files @code{a-suteio.ads/adb} contains some GNAT-specific
11221 subprograms useful for Text_IO operations on unbounded strings:
11225 @item function Get_Line (File : File_Type) return Unbounded_String;
11226 Reads a line from the specified file
11227 and returns the result as an unbounded string.
11229 @item procedure Put (File : File_Type; U : Unbounded_String);
11230 Writes the value of the given unbounded string to the specified file
11231 Similar to the effect of
11232 @code{Put (To_String (U))} except that an extra copy is avoided.
11234 @item procedure Put_Line (File : File_Type; U : Unbounded_String);
11235 Writes the value of the given unbounded string to the specified file,
11236 followed by a @code{New_Line}.
11237 Similar to the effect of @code{Put_Line (To_String (U))} except
11238 that an extra copy is avoided.
11242 In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type}
11243 and is optional. If the parameter is omitted, then the standard input or
11244 output file is referenced as appropriate.
11246 The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library
11247 files @file{a-swuwti.ads} and @file{a-swuwti.adb} provides similar extended
11248 @code{Wide_Text_IO} functionality for unbounded wide strings.
11250 The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library
11251 files @file{a-szuzti.ads} and @file{a-szuzti.adb} provides similar extended
11252 @code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings.
11255 @section Wide_Text_IO
11258 @code{Wide_Text_IO} is similar in most respects to Text_IO, except that
11259 both input and output files may contain special sequences that represent
11260 wide character values. The encoding scheme for a given file may be
11261 specified using a FORM parameter:
11268 as part of the FORM string (WCEM = wide character encoding method),
11269 where @var{x} is one of the following characters
11275 Upper half encoding
11287 The encoding methods match those that
11288 can be used in a source
11289 program, but there is no requirement that the encoding method used for
11290 the source program be the same as the encoding method used for files,
11291 and different files may use different encoding methods.
11293 The default encoding method for the standard files, and for opened files
11294 for which no WCEM parameter is given in the FORM string matches the
11295 wide character encoding specified for the main program (the default
11296 being brackets encoding if no coding method was specified with -gnatW).
11300 In this encoding, a wide character is represented by a five character
11308 where @var{a}, @var{b}, @var{c}, @var{d} are the four hexadecimal
11309 characters (using upper case letters) of the wide character code. For
11310 example, ESC A345 is used to represent the wide character with code
11311 16#A345#. This scheme is compatible with use of the full
11312 @code{Wide_Character} set.
11314 @item Upper Half Coding
11315 The wide character with encoding 16#abcd#, where the upper bit is on
11316 (i.e.@: a is in the range 8-F) is represented as two bytes 16#ab# and
11317 16#cd#. The second byte may never be a format control character, but is
11318 not required to be in the upper half. This method can be also used for
11319 shift-JIS or EUC where the internal coding matches the external coding.
11321 @item Shift JIS Coding
11322 A wide character is represented by a two character sequence 16#ab# and
11323 16#cd#, with the restrictions described for upper half encoding as
11324 described above. The internal character code is the corresponding JIS
11325 character according to the standard algorithm for Shift-JIS
11326 conversion. Only characters defined in the JIS code set table can be
11327 used with this encoding method.
11330 A wide character is represented by a two character sequence 16#ab# and
11331 16#cd#, with both characters being in the upper half. The internal
11332 character code is the corresponding JIS character according to the EUC
11333 encoding algorithm. Only characters defined in the JIS code set table
11334 can be used with this encoding method.
11337 A wide character is represented using
11338 UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
11339 10646-1/Am.2. Depending on the character value, the representation
11340 is a one, two, or three byte sequence:
11343 16#0000#-16#007f#: 2#0xxxxxxx#
11344 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx#
11345 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
11349 where the xxx bits correspond to the left-padded bits of the
11350 16-bit character value. Note that all lower half ASCII characters
11351 are represented as ASCII bytes and all upper half characters and
11352 other wide characters are represented as sequences of upper-half
11353 (The full UTF-8 scheme allows for encoding 31-bit characters as
11354 6-byte sequences, but in this implementation, all UTF-8 sequences
11355 of four or more bytes length will raise a Constraint_Error, as
11356 will all invalid UTF-8 sequences.)
11358 @item Brackets Coding
11359 In this encoding, a wide character is represented by the following eight
11360 character sequence:
11367 where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
11368 characters (using uppercase letters) of the wide character code. For
11369 example, @code{["A345"]} is used to represent the wide character with code
11371 This scheme is compatible with use of the full Wide_Character set.
11372 On input, brackets coding can also be used for upper half characters,
11373 e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation
11374 is only used for wide characters with a code greater than @code{16#FF#}.
11379 For the coding schemes other than Hex and Brackets encoding,
11380 not all wide character
11381 values can be represented. An attempt to output a character that cannot
11382 be represented using the encoding scheme for the file causes
11383 Constraint_Error to be raised. An invalid wide character sequence on
11384 input also causes Constraint_Error to be raised.
11387 * Wide_Text_IO Stream Pointer Positioning::
11388 * Wide_Text_IO Reading and Writing Non-Regular Files::
11391 @node Wide_Text_IO Stream Pointer Positioning
11392 @subsection Stream Pointer Positioning
11395 @code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
11396 of stream pointer positioning (@pxref{Text_IO}). There is one additional
11399 If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the
11400 normal lower ASCII set (i.e.@: a character in the range:
11402 @smallexample @c ada
11403 Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#)
11407 then although the logical position of the file pointer is unchanged by
11408 the @code{Look_Ahead} call, the stream is physically positioned past the
11409 wide character sequence. Again this is to avoid the need for buffering
11410 or backup, and all @code{Wide_Text_IO} routines check the internal
11411 indication that this situation has occurred so that this is not visible
11412 to a normal program using @code{Wide_Text_IO}. However, this discrepancy
11413 can be observed if the wide text file shares a stream with another file.
11415 @node Wide_Text_IO Reading and Writing Non-Regular Files
11416 @subsection Reading and Writing Non-Regular Files
11419 As in the case of Text_IO, when a non-regular file is read, it is
11420 assumed that the file contains no page marks (any form characters are
11421 treated as data characters), and @code{End_Of_Page} always returns
11422 @code{False}. Similarly, the end of file indication is not sticky, so
11423 it is possible to read beyond an end of file.
11425 @node Wide_Wide_Text_IO
11426 @section Wide_Wide_Text_IO
11429 @code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that
11430 both input and output files may contain special sequences that represent
11431 wide wide character values. The encoding scheme for a given file may be
11432 specified using a FORM parameter:
11439 as part of the FORM string (WCEM = wide character encoding method),
11440 where @var{x} is one of the following characters
11446 Upper half encoding
11458 The encoding methods match those that
11459 can be used in a source
11460 program, but there is no requirement that the encoding method used for
11461 the source program be the same as the encoding method used for files,
11462 and different files may use different encoding methods.
11464 The default encoding method for the standard files, and for opened files
11465 for which no WCEM parameter is given in the FORM string matches the
11466 wide character encoding specified for the main program (the default
11467 being brackets encoding if no coding method was specified with -gnatW).
11472 A wide character is represented using
11473 UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
11474 10646-1/Am.2. Depending on the character value, the representation
11475 is a one, two, three, or four byte sequence:
11478 16#000000#-16#00007f#: 2#0xxxxxxx#
11479 16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx#
11480 16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
11481 16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx#
11485 where the xxx bits correspond to the left-padded bits of the
11486 21-bit character value. Note that all lower half ASCII characters
11487 are represented as ASCII bytes and all upper half characters and
11488 other wide characters are represented as sequences of upper-half
11491 @item Brackets Coding
11492 In this encoding, a wide wide character is represented by the following eight
11493 character sequence if is in wide character range
11499 and by the following ten character sequence if not
11502 [ " a b c d e f " ]
11506 where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f}
11507 are the four or six hexadecimal
11508 characters (using uppercase letters) of the wide wide character code. For
11509 example, @code{["01A345"]} is used to represent the wide wide character
11510 with code @code{16#01A345#}.
11512 This scheme is compatible with use of the full Wide_Wide_Character set.
11513 On input, brackets coding can also be used for upper half characters,
11514 e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation
11515 is only used for wide characters with a code greater than @code{16#FF#}.
11520 If is also possible to use the other Wide_Character encoding methods,
11521 such as Shift-JIS, but the other schemes cannot support the full range
11522 of wide wide characters.
11523 An attempt to output a character that cannot
11524 be represented using the encoding scheme for the file causes
11525 Constraint_Error to be raised. An invalid wide character sequence on
11526 input also causes Constraint_Error to be raised.
11529 * Wide_Wide_Text_IO Stream Pointer Positioning::
11530 * Wide_Wide_Text_IO Reading and Writing Non-Regular Files::
11533 @node Wide_Wide_Text_IO Stream Pointer Positioning
11534 @subsection Stream Pointer Positioning
11537 @code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
11538 of stream pointer positioning (@pxref{Text_IO}). There is one additional
11541 If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the
11542 normal lower ASCII set (i.e.@: a character in the range:
11544 @smallexample @c ada
11545 Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#)
11549 then although the logical position of the file pointer is unchanged by
11550 the @code{Look_Ahead} call, the stream is physically positioned past the
11551 wide character sequence. Again this is to avoid the need for buffering
11552 or backup, and all @code{Wide_Wide_Text_IO} routines check the internal
11553 indication that this situation has occurred so that this is not visible
11554 to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy
11555 can be observed if the wide text file shares a stream with another file.
11557 @node Wide_Wide_Text_IO Reading and Writing Non-Regular Files
11558 @subsection Reading and Writing Non-Regular Files
11561 As in the case of Text_IO, when a non-regular file is read, it is
11562 assumed that the file contains no page marks (any form characters are
11563 treated as data characters), and @code{End_Of_Page} always returns
11564 @code{False}. Similarly, the end of file indication is not sticky, so
11565 it is possible to read beyond an end of file.
11571 A stream file is a sequence of bytes, where individual elements are
11572 written to the file as described in the Ada 95 reference manual. The type
11573 @code{Stream_Element} is simply a byte. There are two ways to read or
11574 write a stream file.
11578 The operations @code{Read} and @code{Write} directly read or write a
11579 sequence of stream elements with no control information.
11582 The stream attributes applied to a stream file transfer data in the
11583 manner described for stream attributes.
11587 @section Shared Files
11590 Section A.14 of the Ada 95 Reference Manual allows implementations to
11591 provide a wide variety of behavior if an attempt is made to access the
11592 same external file with two or more internal files.
11594 To provide a full range of functionality, while at the same time
11595 minimizing the problems of portability caused by this implementation
11596 dependence, GNAT handles file sharing as follows:
11600 In the absence of a @samp{shared=@var{xxx}} form parameter, an attempt
11601 to open two or more files with the same full name is considered an error
11602 and is not supported. The exception @code{Use_Error} will be
11603 raised. Note that a file that is not explicitly closed by the program
11604 remains open until the program terminates.
11607 If the form parameter @samp{shared=no} appears in the form string, the
11608 file can be opened or created with its own separate stream identifier,
11609 regardless of whether other files sharing the same external file are
11610 opened. The exact effect depends on how the C stream routines handle
11611 multiple accesses to the same external files using separate streams.
11614 If the form parameter @samp{shared=yes} appears in the form string for
11615 each of two or more files opened using the same full name, the same
11616 stream is shared between these files, and the semantics are as described
11617 in Ada 95 Reference Manual, Section A.14.
11621 When a program that opens multiple files with the same name is ported
11622 from another Ada compiler to GNAT, the effect will be that
11623 @code{Use_Error} is raised.
11625 The documentation of the original compiler and the documentation of the
11626 program should then be examined to determine if file sharing was
11627 expected, and @samp{shared=@var{xxx}} parameters added to @code{Open}
11628 and @code{Create} calls as required.
11630 When a program is ported from GNAT to some other Ada compiler, no
11631 special attention is required unless the @samp{shared=@var{xxx}} form
11632 parameter is used in the program. In this case, you must examine the
11633 documentation of the new compiler to see if it supports the required
11634 file sharing semantics, and form strings modified appropriately. Of
11635 course it may be the case that the program cannot be ported if the
11636 target compiler does not support the required functionality. The best
11637 approach in writing portable code is to avoid file sharing (and hence
11638 the use of the @samp{shared=@var{xxx}} parameter in the form string)
11641 One common use of file sharing in Ada 83 is the use of instantiations of
11642 Sequential_IO on the same file with different types, to achieve
11643 heterogeneous input-output. Although this approach will work in GNAT if
11644 @samp{shared=yes} is specified, it is preferable in Ada 95 to use Stream_IO
11645 for this purpose (using the stream attributes)
11648 @section Open Modes
11651 @code{Open} and @code{Create} calls result in a call to @code{fopen}
11652 using the mode shown in the following table:
11655 @center @code{Open} and @code{Create} Call Modes
11657 @b{OPEN } @b{CREATE}
11658 Append_File "r+" "w+"
11660 Out_File (Direct_IO) "r+" "w"
11661 Out_File (all other cases) "w" "w"
11662 Inout_File "r+" "w+"
11666 If text file translation is required, then either @samp{b} or @samp{t}
11667 is added to the mode, depending on the setting of Text. Text file
11668 translation refers to the mapping of CR/LF sequences in an external file
11669 to LF characters internally. This mapping only occurs in DOS and
11670 DOS-like systems, and is not relevant to other systems.
11672 A special case occurs with Stream_IO@. As shown in the above table, the
11673 file is initially opened in @samp{r} or @samp{w} mode for the
11674 @code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation
11675 subsequently requires switching from reading to writing or vice-versa,
11676 then the file is reopened in @samp{r+} mode to permit the required operation.
11678 @node Operations on C Streams
11679 @section Operations on C Streams
11680 The package @code{Interfaces.C_Streams} provides an Ada program with direct
11681 access to the C library functions for operations on C streams:
11683 @smallexample @c adanocomment
11684 package Interfaces.C_Streams is
11685 -- Note: the reason we do not use the types that are in
11686 -- Interfaces.C is that we want to avoid dragging in the
11687 -- code in this unit if possible.
11688 subtype chars is System.Address;
11689 -- Pointer to null-terminated array of characters
11690 subtype FILEs is System.Address;
11691 -- Corresponds to the C type FILE*
11692 subtype voids is System.Address;
11693 -- Corresponds to the C type void*
11694 subtype int is Integer;
11695 subtype long is Long_Integer;
11696 -- Note: the above types are subtypes deliberately, and it
11697 -- is part of this spec that the above correspondences are
11698 -- guaranteed. This means that it is legitimate to, for
11699 -- example, use Integer instead of int. We provide these
11700 -- synonyms for clarity, but in some cases it may be
11701 -- convenient to use the underlying types (for example to
11702 -- avoid an unnecessary dependency of a spec on the spec
11704 type size_t is mod 2 ** Standard'Address_Size;
11705 NULL_Stream : constant FILEs;
11706 -- Value returned (NULL in C) to indicate an
11707 -- fdopen/fopen/tmpfile error
11708 ----------------------------------
11709 -- Constants Defined in stdio.h --
11710 ----------------------------------
11711 EOF : constant int;
11712 -- Used by a number of routines to indicate error or
11714 IOFBF : constant int;
11715 IOLBF : constant int;
11716 IONBF : constant int;
11717 -- Used to indicate buffering mode for setvbuf call
11718 SEEK_CUR : constant int;
11719 SEEK_END : constant int;
11720 SEEK_SET : constant int;
11721 -- Used to indicate origin for fseek call
11722 function stdin return FILEs;
11723 function stdout return FILEs;
11724 function stderr return FILEs;
11725 -- Streams associated with standard files
11726 --------------------------
11727 -- Standard C functions --
11728 --------------------------
11729 -- The functions selected below are ones that are
11730 -- available in DOS, OS/2, UNIX and Xenix (but not
11731 -- necessarily in ANSI C). These are very thin interfaces
11732 -- which copy exactly the C headers. For more
11733 -- documentation on these functions, see the Microsoft C
11734 -- "Run-Time Library Reference" (Microsoft Press, 1990,
11735 -- ISBN 1-55615-225-6), which includes useful information
11736 -- on system compatibility.
11737 procedure clearerr (stream : FILEs);
11738 function fclose (stream : FILEs) return int;
11739 function fdopen (handle : int; mode : chars) return FILEs;
11740 function feof (stream : FILEs) return int;
11741 function ferror (stream : FILEs) return int;
11742 function fflush (stream : FILEs) return int;
11743 function fgetc (stream : FILEs) return int;
11744 function fgets (strng : chars; n : int; stream : FILEs)
11746 function fileno (stream : FILEs) return int;
11747 function fopen (filename : chars; Mode : chars)
11749 -- Note: to maintain target independence, use
11750 -- text_translation_required, a boolean variable defined in
11751 -- a-sysdep.c to deal with the target dependent text
11752 -- translation requirement. If this variable is set,
11753 -- then b/t should be appended to the standard mode
11754 -- argument to set the text translation mode off or on
11756 function fputc (C : int; stream : FILEs) return int;
11757 function fputs (Strng : chars; Stream : FILEs) return int;
11774 function ftell (stream : FILEs) return long;
11781 function isatty (handle : int) return int;
11782 procedure mktemp (template : chars);
11783 -- The return value (which is just a pointer to template)
11785 procedure rewind (stream : FILEs);
11786 function rmtmp return int;
11794 function tmpfile return FILEs;
11795 function ungetc (c : int; stream : FILEs) return int;
11796 function unlink (filename : chars) return int;
11797 ---------------------
11798 -- Extra functions --
11799 ---------------------
11800 -- These functions supply slightly thicker bindings than
11801 -- those above. They are derived from functions in the
11802 -- C Run-Time Library, but may do a bit more work than
11803 -- just directly calling one of the Library functions.
11804 function is_regular_file (handle : int) return int;
11805 -- Tests if given handle is for a regular file (result 1)
11806 -- or for a non-regular file (pipe or device, result 0).
11807 ---------------------------------
11808 -- Control of Text/Binary Mode --
11809 ---------------------------------
11810 -- If text_translation_required is true, then the following
11811 -- functions may be used to dynamically switch a file from
11812 -- binary to text mode or vice versa. These functions have
11813 -- no effect if text_translation_required is false (i.e. in
11814 -- normal UNIX mode). Use fileno to get a stream handle.
11815 procedure set_binary_mode (handle : int);
11816 procedure set_text_mode (handle : int);
11817 ----------------------------
11818 -- Full Path Name support --
11819 ----------------------------
11820 procedure full_name (nam : chars; buffer : chars);
11821 -- Given a NUL terminated string representing a file
11822 -- name, returns in buffer a NUL terminated string
11823 -- representing the full path name for the file name.
11824 -- On systems where it is relevant the drive is also
11825 -- part of the full path name. It is the responsibility
11826 -- of the caller to pass an actual parameter for buffer
11827 -- that is big enough for any full path name. Use
11828 -- max_path_len given below as the size of buffer.
11829 max_path_len : integer;
11830 -- Maximum length of an allowable full path name on the
11831 -- system, including a terminating NUL character.
11832 end Interfaces.C_Streams;
11835 @node Interfacing to C Streams
11836 @section Interfacing to C Streams
11839 The packages in this section permit interfacing Ada files to C Stream
11842 @smallexample @c ada
11843 with Interfaces.C_Streams;
11844 package Ada.Sequential_IO.C_Streams is
11845 function C_Stream (F : File_Type)
11846 return Interfaces.C_Streams.FILEs;
11848 (File : in out File_Type;
11849 Mode : in File_Mode;
11850 C_Stream : in Interfaces.C_Streams.FILEs;
11851 Form : in String := "");
11852 end Ada.Sequential_IO.C_Streams;
11854 with Interfaces.C_Streams;
11855 package Ada.Direct_IO.C_Streams is
11856 function C_Stream (F : File_Type)
11857 return Interfaces.C_Streams.FILEs;
11859 (File : in out File_Type;
11860 Mode : in File_Mode;
11861 C_Stream : in Interfaces.C_Streams.FILEs;
11862 Form : in String := "");
11863 end Ada.Direct_IO.C_Streams;
11865 with Interfaces.C_Streams;
11866 package Ada.Text_IO.C_Streams is
11867 function C_Stream (F : File_Type)
11868 return Interfaces.C_Streams.FILEs;
11870 (File : in out File_Type;
11871 Mode : in File_Mode;
11872 C_Stream : in Interfaces.C_Streams.FILEs;
11873 Form : in String := "");
11874 end Ada.Text_IO.C_Streams;
11876 with Interfaces.C_Streams;
11877 package Ada.Wide_Text_IO.C_Streams is
11878 function C_Stream (F : File_Type)
11879 return Interfaces.C_Streams.FILEs;
11881 (File : in out File_Type;
11882 Mode : in File_Mode;
11883 C_Stream : in Interfaces.C_Streams.FILEs;
11884 Form : in String := "");
11885 end Ada.Wide_Text_IO.C_Streams;
11887 with Interfaces.C_Streams;
11888 package Ada.Wide_Wide_Text_IO.C_Streams is
11889 function C_Stream (F : File_Type)
11890 return Interfaces.C_Streams.FILEs;
11892 (File : in out File_Type;
11893 Mode : in File_Mode;
11894 C_Stream : in Interfaces.C_Streams.FILEs;
11895 Form : in String := "");
11896 end Ada.Wide_Wide_Text_IO.C_Streams;
11898 with Interfaces.C_Streams;
11899 package Ada.Stream_IO.C_Streams is
11900 function C_Stream (F : File_Type)
11901 return Interfaces.C_Streams.FILEs;
11903 (File : in out File_Type;
11904 Mode : in File_Mode;
11905 C_Stream : in Interfaces.C_Streams.FILEs;
11906 Form : in String := "");
11907 end Ada.Stream_IO.C_Streams;
11911 In each of these six packages, the @code{C_Stream} function obtains the
11912 @code{FILE} pointer from a currently opened Ada file. It is then
11913 possible to use the @code{Interfaces.C_Streams} package to operate on
11914 this stream, or the stream can be passed to a C program which can
11915 operate on it directly. Of course the program is responsible for
11916 ensuring that only appropriate sequences of operations are executed.
11918 One particular use of relevance to an Ada program is that the
11919 @code{setvbuf} function can be used to control the buffering of the
11920 stream used by an Ada file. In the absence of such a call the standard
11921 default buffering is used.
11923 The @code{Open} procedures in these packages open a file giving an
11924 existing C Stream instead of a file name. Typically this stream is
11925 imported from a C program, allowing an Ada file to operate on an
11928 @node The GNAT Library
11929 @chapter The GNAT Library
11932 The GNAT library contains a number of general and special purpose packages.
11933 It represents functionality that the GNAT developers have found useful, and
11934 which is made available to GNAT users. The packages described here are fully
11935 supported, and upwards compatibility will be maintained in future releases,
11936 so you can use these facilities with the confidence that the same functionality
11937 will be available in future releases.
11939 The chapter here simply gives a brief summary of the facilities available.
11940 The full documentation is found in the spec file for the package. The full
11941 sources of these library packages, including both spec and body, are provided
11942 with all GNAT releases. For example, to find out the full specifications of
11943 the SPITBOL pattern matching capability, including a full tutorial and
11944 extensive examples, look in the @file{g-spipat.ads} file in the library.
11946 For each entry here, the package name (as it would appear in a @code{with}
11947 clause) is given, followed by the name of the corresponding spec file in
11948 parentheses. The packages are children in four hierarchies, @code{Ada},
11949 @code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a
11950 GNAT-specific hierarchy.
11952 Note that an application program should only use packages in one of these
11953 four hierarchies if the package is defined in the Ada Reference Manual,
11954 or is listed in this section of the GNAT Programmers Reference Manual.
11955 All other units should be considered internal implementation units and
11956 should not be directly @code{with}'ed by application code. The use of
11957 a @code{with} statement that references one of these internal implementation
11958 units makes an application potentially dependent on changes in versions
11959 of GNAT, and will generate a warning message.
11962 * Ada.Characters.Latin_9 (a-chlat9.ads)::
11963 * Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
11964 * Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
11965 * Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads)::
11966 * Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads)::
11967 * Ada.Command_Line.Remove (a-colire.ads)::
11968 * Ada.Command_Line.Environment (a-colien.ads)::
11969 * Ada.Direct_IO.C_Streams (a-diocst.ads)::
11970 * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
11971 * Ada.Exceptions.Traceback (a-exctra.ads)::
11972 * Ada.Sequential_IO.C_Streams (a-siocst.ads)::
11973 * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
11974 * Ada.Strings.Unbounded.Text_IO (a-suteio.ads)::
11975 * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
11976 * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
11977 * Ada.Text_IO.C_Streams (a-tiocst.ads)::
11978 * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
11979 * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
11980 * GNAT.Array_Split (g-arrspl.ads)::
11981 * GNAT.AWK (g-awk.ads)::
11982 * GNAT.Bounded_Buffers (g-boubuf.ads)::
11983 * GNAT.Bounded_Mailboxes (g-boumai.ads)::
11984 * GNAT.Bubble_Sort (g-bubsor.ads)::
11985 * GNAT.Bubble_Sort_A (g-busora.ads)::
11986 * GNAT.Bubble_Sort_G (g-busorg.ads)::
11987 * GNAT.Calendar (g-calend.ads)::
11988 * GNAT.Calendar.Time_IO (g-catiio.ads)::
11989 * GNAT.CRC32 (g-crc32.ads)::
11990 * GNAT.Case_Util (g-casuti.ads)::
11991 * GNAT.CGI (g-cgi.ads)::
11992 * GNAT.CGI.Cookie (g-cgicoo.ads)::
11993 * GNAT.CGI.Debug (g-cgideb.ads)::
11994 * GNAT.Command_Line (g-comlin.ads)::
11995 * GNAT.Compiler_Version (g-comver.ads)::
11996 * GNAT.Ctrl_C (g-ctrl_c.ads)::
11997 * GNAT.Current_Exception (g-curexc.ads)::
11998 * GNAT.Debug_Pools (g-debpoo.ads)::
11999 * GNAT.Debug_Utilities (g-debuti.ads)::
12000 * GNAT.Directory_Operations (g-dirope.ads)::
12001 * GNAT.Dynamic_HTables (g-dynhta.ads)::
12002 * GNAT.Dynamic_Tables (g-dyntab.ads)::
12003 * GNAT.Exception_Actions (g-excact.ads)::
12004 * GNAT.Exception_Traces (g-exctra.ads)::
12005 * GNAT.Exceptions (g-except.ads)::
12006 * GNAT.Expect (g-expect.ads)::
12007 * GNAT.Float_Control (g-flocon.ads)::
12008 * GNAT.Heap_Sort (g-heasor.ads)::
12009 * GNAT.Heap_Sort_A (g-hesora.ads)::
12010 * GNAT.Heap_Sort_G (g-hesorg.ads)::
12011 * GNAT.HTable (g-htable.ads)::
12012 * GNAT.IO (g-io.ads)::
12013 * GNAT.IO_Aux (g-io_aux.ads)::
12014 * GNAT.Lock_Files (g-locfil.ads)::
12015 * GNAT.MD5 (g-md5.ads)::
12016 * GNAT.Memory_Dump (g-memdum.ads)::
12017 * GNAT.Most_Recent_Exception (g-moreex.ads)::
12018 * GNAT.OS_Lib (g-os_lib.ads)::
12019 * GNAT.Perfect_Hash_Generators (g-pehage.ads)::
12020 * GNAT.Regexp (g-regexp.ads)::
12021 * GNAT.Registry (g-regist.ads)::
12022 * GNAT.Regpat (g-regpat.ads)::
12023 * GNAT.Secondary_Stack_Info (g-sestin.ads)::
12024 * GNAT.Semaphores (g-semaph.ads)::
12025 * GNAT.Signals (g-signal.ads)::
12026 * GNAT.Sockets (g-socket.ads)::
12027 * GNAT.Source_Info (g-souinf.ads)::
12028 * GNAT.Spell_Checker (g-speche.ads)::
12029 * GNAT.Spitbol.Patterns (g-spipat.ads)::
12030 * GNAT.Spitbol (g-spitbo.ads)::
12031 * GNAT.Spitbol.Table_Boolean (g-sptabo.ads)::
12032 * GNAT.Spitbol.Table_Integer (g-sptain.ads)::
12033 * GNAT.Spitbol.Table_VString (g-sptavs.ads)::
12034 * GNAT.Strings (g-string.ads)::
12035 * GNAT.String_Split (g-strspl.ads)::
12036 * GNAT.UTF_32 (g-utf_32.ads)::
12037 * GNAT.Table (g-table.ads)::
12038 * GNAT.Task_Lock (g-tasloc.ads)::
12039 * GNAT.Threads (g-thread.ads)::
12040 * GNAT.Traceback (g-traceb.ads)::
12041 * GNAT.Traceback.Symbolic (g-trasym.ads)::
12042 * GNAT.Wide_String_Split (g-wistsp.ads)::
12043 * GNAT.Wide_Wide_String_Split (g-zistsp.ads)::
12044 * Interfaces.C.Extensions (i-cexten.ads)::
12045 * Interfaces.C.Streams (i-cstrea.ads)::
12046 * Interfaces.CPP (i-cpp.ads)::
12047 * Interfaces.Os2lib (i-os2lib.ads)::
12048 * Interfaces.Os2lib.Errors (i-os2err.ads)::
12049 * Interfaces.Os2lib.Synchronization (i-os2syn.ads)::
12050 * Interfaces.Os2lib.Threads (i-os2thr.ads)::
12051 * Interfaces.Packed_Decimal (i-pacdec.ads)::
12052 * Interfaces.VxWorks (i-vxwork.ads)::
12053 * Interfaces.VxWorks.IO (i-vxwoio.ads)::
12054 * System.Address_Image (s-addima.ads)::
12055 * System.Assertions (s-assert.ads)::
12056 * System.Memory (s-memory.ads)::
12057 * System.Partition_Interface (s-parint.ads)::
12058 * System.Restrictions (s-restri.ads)::
12059 * System.Rident (s-rident.ads)::
12060 * System.Task_Info (s-tasinf.ads)::
12061 * System.Wch_Cnv (s-wchcnv.ads)::
12062 * System.Wch_Con (s-wchcon.ads)::
12065 @node Ada.Characters.Latin_9 (a-chlat9.ads)
12066 @section @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads})
12067 @cindex @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads})
12068 @cindex Latin_9 constants for Character
12071 This child of @code{Ada.Characters}
12072 provides a set of definitions corresponding to those in the
12073 RM-defined package @code{Ada.Characters.Latin_1} but with the
12074 few modifications required for @code{Latin-9}
12075 The provision of such a package
12076 is specifically authorized by the Ada Reference Manual
12079 @node Ada.Characters.Wide_Latin_1 (a-cwila1.ads)
12080 @section @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads})
12081 @cindex @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads})
12082 @cindex Latin_1 constants for Wide_Character
12085 This child of @code{Ada.Characters}
12086 provides a set of definitions corresponding to those in the
12087 RM-defined package @code{Ada.Characters.Latin_1} but with the
12088 types of the constants being @code{Wide_Character}
12089 instead of @code{Character}. The provision of such a package
12090 is specifically authorized by the Ada Reference Manual
12093 @node Ada.Characters.Wide_Latin_9 (a-cwila9.ads)
12094 @section @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads})
12095 @cindex @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads})
12096 @cindex Latin_9 constants for Wide_Character
12099 This child of @code{Ada.Characters}
12100 provides a set of definitions corresponding to those in the
12101 GNAT defined package @code{Ada.Characters.Latin_9} but with the
12102 types of the constants being @code{Wide_Character}
12103 instead of @code{Character}. The provision of such a package
12104 is specifically authorized by the Ada Reference Manual
12107 @node Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads)
12108 @section @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-czila1.ads})
12109 @cindex @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-czila1.ads})
12110 @cindex Latin_1 constants for Wide_Wide_Character
12113 This child of @code{Ada.Characters}
12114 provides a set of definitions corresponding to those in the
12115 RM-defined package @code{Ada.Characters.Latin_1} but with the
12116 types of the constants being @code{Wide_Wide_Character}
12117 instead of @code{Character}. The provision of such a package
12118 is specifically authorized by the Ada Reference Manual
12121 @node Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads)
12122 @section @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-czila9.ads})
12123 @cindex @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-czila9.ads})
12124 @cindex Latin_9 constants for Wide_Wide_Character
12127 This child of @code{Ada.Characters}
12128 provides a set of definitions corresponding to those in the
12129 GNAT defined package @code{Ada.Characters.Latin_9} but with the
12130 types of the constants being @code{Wide_Wide_Character}
12131 instead of @code{Character}. The provision of such a package
12132 is specifically authorized by the Ada Reference Manual
12135 @node Ada.Command_Line.Remove (a-colire.ads)
12136 @section @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
12137 @cindex @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
12138 @cindex Removing command line arguments
12139 @cindex Command line, argument removal
12142 This child of @code{Ada.Command_Line}
12143 provides a mechanism for logically removing
12144 arguments from the argument list. Once removed, an argument is not visible
12145 to further calls on the subprograms in @code{Ada.Command_Line} will not
12146 see the removed argument.
12148 @node Ada.Command_Line.Environment (a-colien.ads)
12149 @section @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
12150 @cindex @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
12151 @cindex Environment entries
12154 This child of @code{Ada.Command_Line}
12155 provides a mechanism for obtaining environment values on systems
12156 where this concept makes sense.
12158 @node Ada.Direct_IO.C_Streams (a-diocst.ads)
12159 @section @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads})
12160 @cindex @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads})
12161 @cindex C Streams, Interfacing with Direct_IO
12164 This package provides subprograms that allow interfacing between
12165 C streams and @code{Direct_IO}. The stream identifier can be
12166 extracted from a file opened on the Ada side, and an Ada file
12167 can be constructed from a stream opened on the C side.
12169 @node Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)
12170 @section @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads})
12171 @cindex @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads})
12172 @cindex Null_Occurrence, testing for
12175 This child subprogram provides a way of testing for the null
12176 exception occurrence (@code{Null_Occurrence}) without raising
12179 @node Ada.Exceptions.Traceback (a-exctra.ads)
12180 @section @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads})
12181 @cindex @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads})
12182 @cindex Traceback for Exception Occurrence
12185 This child package provides the subprogram (@code{Tracebacks}) to
12186 give a traceback array of addresses based on an exception
12189 @node Ada.Sequential_IO.C_Streams (a-siocst.ads)
12190 @section @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads})
12191 @cindex @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads})
12192 @cindex C Streams, Interfacing with Sequential_IO
12195 This package provides subprograms that allow interfacing between
12196 C streams and @code{Sequential_IO}. The stream identifier can be
12197 extracted from a file opened on the Ada side, and an Ada file
12198 can be constructed from a stream opened on the C side.
12200 @node Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)
12201 @section @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads})
12202 @cindex @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads})
12203 @cindex C Streams, Interfacing with Stream_IO
12206 This package provides subprograms that allow interfacing between
12207 C streams and @code{Stream_IO}. The stream identifier can be
12208 extracted from a file opened on the Ada side, and an Ada file
12209 can be constructed from a stream opened on the C side.
12211 @node Ada.Strings.Unbounded.Text_IO (a-suteio.ads)
12212 @section @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads})
12213 @cindex @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads})
12214 @cindex @code{Unbounded_String}, IO support
12215 @cindex @code{Text_IO}, extensions for unbounded strings
12218 This package provides subprograms for Text_IO for unbounded
12219 strings, avoiding the necessity for an intermediate operation
12220 with ordinary strings.
12222 @node Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)
12223 @section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads})
12224 @cindex @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads})
12225 @cindex @code{Unbounded_Wide_String}, IO support
12226 @cindex @code{Text_IO}, extensions for unbounded wide strings
12229 This package provides subprograms for Text_IO for unbounded
12230 wide strings, avoiding the necessity for an intermediate operation
12231 with ordinary wide strings.
12233 @node Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)
12234 @section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads})
12235 @cindex @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads})
12236 @cindex @code{Unbounded_Wide_Wide_String}, IO support
12237 @cindex @code{Text_IO}, extensions for unbounded wide wide strings
12240 This package provides subprograms for Text_IO for unbounded
12241 wide wide strings, avoiding the necessity for an intermediate operation
12242 with ordinary wide wide strings.
12244 @node Ada.Text_IO.C_Streams (a-tiocst.ads)
12245 @section @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads})
12246 @cindex @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads})
12247 @cindex C Streams, Interfacing with @code{Text_IO}
12250 This package provides subprograms that allow interfacing between
12251 C streams and @code{Text_IO}. The stream identifier can be
12252 extracted from a file opened on the Ada side, and an Ada file
12253 can be constructed from a stream opened on the C side.
12255 @node Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)
12256 @section @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads})
12257 @cindex @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads})
12258 @cindex C Streams, Interfacing with @code{Wide_Text_IO}
12261 This package provides subprograms that allow interfacing between
12262 C streams and @code{Wide_Text_IO}. The stream identifier can be
12263 extracted from a file opened on the Ada side, and an Ada file
12264 can be constructed from a stream opened on the C side.
12266 @node Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)
12267 @section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads})
12268 @cindex @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads})
12269 @cindex C Streams, Interfacing with @code{Wide_Wide_Text_IO}
12272 This package provides subprograms that allow interfacing between
12273 C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be
12274 extracted from a file opened on the Ada side, and an Ada file
12275 can be constructed from a stream opened on the C side.
12278 @node GNAT.Array_Split (g-arrspl.ads)
12279 @section @code{GNAT.Array_Split} (@file{g-arrspl.ads})
12280 @cindex @code{GNAT.Array_Split} (@file{g-arrspl.ads})
12281 @cindex Array splitter
12284 Useful array-manipulation routines: given a set of separators, split
12285 an array wherever the separators appear, and provide direct access
12286 to the resulting slices.
12288 @node GNAT.AWK (g-awk.ads)
12289 @section @code{GNAT.AWK} (@file{g-awk.ads})
12290 @cindex @code{GNAT.AWK} (@file{g-awk.ads})
12295 Provides AWK-like parsing functions, with an easy interface for parsing one
12296 or more files containing formatted data. The file is viewed as a database
12297 where each record is a line and a field is a data element in this line.
12299 @node GNAT.Bounded_Buffers (g-boubuf.ads)
12300 @section @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads})
12301 @cindex @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads})
12303 @cindex Bounded Buffers
12306 Provides a concurrent generic bounded buffer abstraction. Instances are
12307 useful directly or as parts of the implementations of other abstractions,
12310 @node GNAT.Bounded_Mailboxes (g-boumai.ads)
12311 @section @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads})
12312 @cindex @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads})
12317 Provides a thread-safe asynchronous intertask mailbox communication facility.
12319 @node GNAT.Bubble_Sort (g-bubsor.ads)
12320 @section @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads})
12321 @cindex @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads})
12323 @cindex Bubble sort
12326 Provides a general implementation of bubble sort usable for sorting arbitrary
12327 data items. Exchange and comparison procedures are provided by passing
12328 access-to-procedure values.
12330 @node GNAT.Bubble_Sort_A (g-busora.ads)
12331 @section @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads})
12332 @cindex @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads})
12334 @cindex Bubble sort
12337 Provides a general implementation of bubble sort usable for sorting arbitrary
12338 data items. Move and comparison procedures are provided by passing
12339 access-to-procedure values. This is an older version, retained for
12340 compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable.
12342 @node GNAT.Bubble_Sort_G (g-busorg.ads)
12343 @section @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads})
12344 @cindex @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads})
12346 @cindex Bubble sort
12349 Similar to @code{Bubble_Sort_A} except that the move and sorting procedures
12350 are provided as generic parameters, this improves efficiency, especially
12351 if the procedures can be inlined, at the expense of duplicating code for
12352 multiple instantiations.
12354 @node GNAT.Calendar (g-calend.ads)
12355 @section @code{GNAT.Calendar} (@file{g-calend.ads})
12356 @cindex @code{GNAT.Calendar} (@file{g-calend.ads})
12357 @cindex @code{Calendar}
12360 Extends the facilities provided by @code{Ada.Calendar} to include handling
12361 of days of the week, an extended @code{Split} and @code{Time_Of} capability.
12362 Also provides conversion of @code{Ada.Calendar.Time} values to and from the
12363 C @code{timeval} format.
12365 @node GNAT.Calendar.Time_IO (g-catiio.ads)
12366 @section @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads})
12367 @cindex @code{Calendar}
12369 @cindex @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads})
12371 @node GNAT.CRC32 (g-crc32.ads)
12372 @section @code{GNAT.CRC32} (@file{g-crc32.ads})
12373 @cindex @code{GNAT.CRC32} (@file{g-crc32.ads})
12375 @cindex Cyclic Redundancy Check
12378 This package implements the CRC-32 algorithm. For a full description
12379 of this algorithm see
12380 ``Computation of Cyclic Redundancy Checks via Table Look-Up'',
12381 @cite{Communications of the ACM}, Vol.@: 31 No.@: 8, pp.@: 1008-1013,
12382 Aug.@: 1988. Sarwate, D.V@.
12385 Provides an extended capability for formatted output of time values with
12386 full user control over the format. Modeled on the GNU Date specification.
12388 @node GNAT.Case_Util (g-casuti.ads)
12389 @section @code{GNAT.Case_Util} (@file{g-casuti.ads})
12390 @cindex @code{GNAT.Case_Util} (@file{g-casuti.ads})
12391 @cindex Casing utilities
12392 @cindex Character handling (@code{GNAT.Case_Util})
12395 A set of simple routines for handling upper and lower casing of strings
12396 without the overhead of the full casing tables
12397 in @code{Ada.Characters.Handling}.
12399 @node GNAT.CGI (g-cgi.ads)
12400 @section @code{GNAT.CGI} (@file{g-cgi.ads})
12401 @cindex @code{GNAT.CGI} (@file{g-cgi.ads})
12402 @cindex CGI (Common Gateway Interface)
12405 This is a package for interfacing a GNAT program with a Web server via the
12406 Common Gateway Interface (CGI)@. Basically this package parses the CGI
12407 parameters, which are a set of key/value pairs sent by the Web server. It
12408 builds a table whose index is the key and provides some services to deal
12411 @node GNAT.CGI.Cookie (g-cgicoo.ads)
12412 @section @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads})
12413 @cindex @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads})
12414 @cindex CGI (Common Gateway Interface) cookie support
12415 @cindex Cookie support in CGI
12418 This is a package to interface a GNAT program with a Web server via the
12419 Common Gateway Interface (CGI). It exports services to deal with Web
12420 cookies (piece of information kept in the Web client software).
12422 @node GNAT.CGI.Debug (g-cgideb.ads)
12423 @section @code{GNAT.CGI.Debug} (@file{g-cgideb.ads})
12424 @cindex @code{GNAT.CGI.Debug} (@file{g-cgideb.ads})
12425 @cindex CGI (Common Gateway Interface) debugging
12428 This is a package to help debugging CGI (Common Gateway Interface)
12429 programs written in Ada.
12431 @node GNAT.Command_Line (g-comlin.ads)
12432 @section @code{GNAT.Command_Line} (@file{g-comlin.ads})
12433 @cindex @code{GNAT.Command_Line} (@file{g-comlin.ads})
12434 @cindex Command line
12437 Provides a high level interface to @code{Ada.Command_Line} facilities,
12438 including the ability to scan for named switches with optional parameters
12439 and expand file names using wild card notations.
12441 @node GNAT.Compiler_Version (g-comver.ads)
12442 @section @code{GNAT.Compiler_Version} (@file{g-comver.ads})
12443 @cindex @code{GNAT.Compiler_Version} (@file{g-comver.ads})
12444 @cindex Compiler Version
12445 @cindex Version, of compiler
12448 Provides a routine for obtaining the version of the compiler used to
12449 compile the program. More accurately this is the version of the binder
12450 used to bind the program (this will normally be the same as the version
12451 of the compiler if a consistent tool set is used to compile all units
12454 @node GNAT.Ctrl_C (g-ctrl_c.ads)
12455 @section @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads})
12456 @cindex @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads})
12460 Provides a simple interface to handle Ctrl-C keyboard events.
12462 @node GNAT.Current_Exception (g-curexc.ads)
12463 @section @code{GNAT.Current_Exception} (@file{g-curexc.ads})
12464 @cindex @code{GNAT.Current_Exception} (@file{g-curexc.ads})
12465 @cindex Current exception
12466 @cindex Exception retrieval
12469 Provides access to information on the current exception that has been raised
12470 without the need for using the Ada-95 exception choice parameter specification
12471 syntax. This is particularly useful in simulating typical facilities for
12472 obtaining information about exceptions provided by Ada 83 compilers.
12474 @node GNAT.Debug_Pools (g-debpoo.ads)
12475 @section @code{GNAT.Debug_Pools} (@file{g-debpoo.ads})
12476 @cindex @code{GNAT.Debug_Pools} (@file{g-debpoo.ads})
12478 @cindex Debug pools
12479 @cindex Memory corruption debugging
12482 Provide a debugging storage pools that helps tracking memory corruption
12483 problems. See section ``Finding memory problems with GNAT Debug Pool'' in
12484 the @cite{GNAT User's Guide}.
12486 @node GNAT.Debug_Utilities (g-debuti.ads)
12487 @section @code{GNAT.Debug_Utilities} (@file{g-debuti.ads})
12488 @cindex @code{GNAT.Debug_Utilities} (@file{g-debuti.ads})
12492 Provides a few useful utilities for debugging purposes, including conversion
12493 to and from string images of address values. Supports both C and Ada formats
12494 for hexadecimal literals.
12496 @node GNAT.Directory_Operations (g-dirope.ads)
12497 @section @code{GNAT.Directory_Operations} (g-dirope.ads)
12498 @cindex @code{GNAT.Directory_Operations} (g-dirope.ads)
12499 @cindex Directory operations
12502 Provides a set of routines for manipulating directories, including changing
12503 the current directory, making new directories, and scanning the files in a
12506 @node GNAT.Dynamic_HTables (g-dynhta.ads)
12507 @section @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads})
12508 @cindex @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads})
12509 @cindex Hash tables
12512 A generic implementation of hash tables that can be used to hash arbitrary
12513 data. Provided in two forms, a simple form with built in hash functions,
12514 and a more complex form in which the hash function is supplied.
12517 This package provides a facility similar to that of @code{GNAT.HTable},
12518 except that this package declares a type that can be used to define
12519 dynamic instances of the hash table, while an instantiation of
12520 @code{GNAT.HTable} creates a single instance of the hash table.
12522 @node GNAT.Dynamic_Tables (g-dyntab.ads)
12523 @section @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads})
12524 @cindex @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads})
12525 @cindex Table implementation
12526 @cindex Arrays, extendable
12529 A generic package providing a single dimension array abstraction where the
12530 length of the array can be dynamically modified.
12533 This package provides a facility similar to that of @code{GNAT.Table},
12534 except that this package declares a type that can be used to define
12535 dynamic instances of the table, while an instantiation of
12536 @code{GNAT.Table} creates a single instance of the table type.
12538 @node GNAT.Exception_Actions (g-excact.ads)
12539 @section @code{GNAT.Exception_Actions} (@file{g-excact.ads})
12540 @cindex @code{GNAT.Exception_Actions} (@file{g-excact.ads})
12541 @cindex Exception actions
12544 Provides callbacks when an exception is raised. Callbacks can be registered
12545 for specific exceptions, or when any exception is raised. This
12546 can be used for instance to force a core dump to ease debugging.
12548 @node GNAT.Exception_Traces (g-exctra.ads)
12549 @section @code{GNAT.Exception_Traces} (@file{g-exctra.ads})
12550 @cindex @code{GNAT.Exception_Traces} (@file{g-exctra.ads})
12551 @cindex Exception traces
12555 Provides an interface allowing to control automatic output upon exception
12558 @node GNAT.Exceptions (g-except.ads)
12559 @section @code{GNAT.Exceptions} (@file{g-expect.ads})
12560 @cindex @code{GNAT.Exceptions} (@file{g-expect.ads})
12561 @cindex Exceptions, Pure
12562 @cindex Pure packages, exceptions
12565 Normally it is not possible to raise an exception with
12566 a message from a subprogram in a pure package, since the
12567 necessary types and subprograms are in @code{Ada.Exceptions}
12568 which is not a pure unit. @code{GNAT.Exceptions} provides a
12569 facility for getting around this limitation for a few
12570 predefined exceptions, and for example allow raising
12571 @code{Constraint_Error} with a message from a pure subprogram.
12573 @node GNAT.Expect (g-expect.ads)
12574 @section @code{GNAT.Expect} (@file{g-expect.ads})
12575 @cindex @code{GNAT.Expect} (@file{g-expect.ads})
12578 Provides a set of subprograms similar to what is available
12579 with the standard Tcl Expect tool.
12580 It allows you to easily spawn and communicate with an external process.
12581 You can send commands or inputs to the process, and compare the output
12582 with some expected regular expression. Currently @code{GNAT.Expect}
12583 is implemented on all native GNAT ports except for OpenVMS@.
12584 It is not implemented for cross ports, and in particular is not
12585 implemented for VxWorks or LynxOS@.
12587 @node GNAT.Float_Control (g-flocon.ads)
12588 @section @code{GNAT.Float_Control} (@file{g-flocon.ads})
12589 @cindex @code{GNAT.Float_Control} (@file{g-flocon.ads})
12590 @cindex Floating-Point Processor
12593 Provides an interface for resetting the floating-point processor into the
12594 mode required for correct semantic operation in Ada. Some third party
12595 library calls may cause this mode to be modified, and the Reset procedure
12596 in this package can be used to reestablish the required mode.
12598 @node GNAT.Heap_Sort (g-heasor.ads)
12599 @section @code{GNAT.Heap_Sort} (@file{g-heasor.ads})
12600 @cindex @code{GNAT.Heap_Sort} (@file{g-heasor.ads})
12604 Provides a general implementation of heap sort usable for sorting arbitrary
12605 data items. Exchange and comparison procedures are provided by passing
12606 access-to-procedure values. The algorithm used is a modified heap sort
12607 that performs approximately N*log(N) comparisons in the worst case.
12609 @node GNAT.Heap_Sort_A (g-hesora.ads)
12610 @section @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads})
12611 @cindex @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads})
12615 Provides a general implementation of heap sort usable for sorting arbitrary
12616 data items. Move and comparison procedures are provided by passing
12617 access-to-procedure values. The algorithm used is a modified heap sort
12618 that performs approximately N*log(N) comparisons in the worst case.
12619 This differs from @code{GNAT.Heap_Sort} in having a less convenient
12620 interface, but may be slightly more efficient.
12622 @node GNAT.Heap_Sort_G (g-hesorg.ads)
12623 @section @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads})
12624 @cindex @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads})
12628 Similar to @code{Heap_Sort_A} except that the move and sorting procedures
12629 are provided as generic parameters, this improves efficiency, especially
12630 if the procedures can be inlined, at the expense of duplicating code for
12631 multiple instantiations.
12633 @node GNAT.HTable (g-htable.ads)
12634 @section @code{GNAT.HTable} (@file{g-htable.ads})
12635 @cindex @code{GNAT.HTable} (@file{g-htable.ads})
12636 @cindex Hash tables
12639 A generic implementation of hash tables that can be used to hash arbitrary
12640 data. Provides two approaches, one a simple static approach, and the other
12641 allowing arbitrary dynamic hash tables.
12643 @node GNAT.IO (g-io.ads)
12644 @section @code{GNAT.IO} (@file{g-io.ads})
12645 @cindex @code{GNAT.IO} (@file{g-io.ads})
12647 @cindex Input/Output facilities
12650 A simple preelaborable input-output package that provides a subset of
12651 simple Text_IO functions for reading characters and strings from
12652 Standard_Input, and writing characters, strings and integers to either
12653 Standard_Output or Standard_Error.
12655 @node GNAT.IO_Aux (g-io_aux.ads)
12656 @section @code{GNAT.IO_Aux} (@file{g-io_aux.ads})
12657 @cindex @code{GNAT.IO_Aux} (@file{g-io_aux.ads})
12659 @cindex Input/Output facilities
12661 Provides some auxiliary functions for use with Text_IO, including a test
12662 for whether a file exists, and functions for reading a line of text.
12664 @node GNAT.Lock_Files (g-locfil.ads)
12665 @section @code{GNAT.Lock_Files} (@file{g-locfil.ads})
12666 @cindex @code{GNAT.Lock_Files} (@file{g-locfil.ads})
12667 @cindex File locking
12668 @cindex Locking using files
12671 Provides a general interface for using files as locks. Can be used for
12672 providing program level synchronization.
12674 @node GNAT.MD5 (g-md5.ads)
12675 @section @code{GNAT.MD5} (@file{g-md5.ads})
12676 @cindex @code{GNAT.MD5} (@file{g-md5.ads})
12677 @cindex Message Digest MD5
12680 Implements the MD5 Message-Digest Algorithm as described in RFC 1321.
12682 @node GNAT.Memory_Dump (g-memdum.ads)
12683 @section @code{GNAT.Memory_Dump} (@file{g-memdum.ads})
12684 @cindex @code{GNAT.Memory_Dump} (@file{g-memdum.ads})
12685 @cindex Dump Memory
12688 Provides a convenient routine for dumping raw memory to either the
12689 standard output or standard error files. Uses GNAT.IO for actual
12692 @node GNAT.Most_Recent_Exception (g-moreex.ads)
12693 @section @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads})
12694 @cindex @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads})
12695 @cindex Exception, obtaining most recent
12698 Provides access to the most recently raised exception. Can be used for
12699 various logging purposes, including duplicating functionality of some
12700 Ada 83 implementation dependent extensions.
12702 @node GNAT.OS_Lib (g-os_lib.ads)
12703 @section @code{GNAT.OS_Lib} (@file{g-os_lib.ads})
12704 @cindex @code{GNAT.OS_Lib} (@file{g-os_lib.ads})
12705 @cindex Operating System interface
12706 @cindex Spawn capability
12709 Provides a range of target independent operating system interface functions,
12710 including time/date management, file operations, subprocess management,
12711 including a portable spawn procedure, and access to environment variables
12712 and error return codes.
12714 @node GNAT.Perfect_Hash_Generators (g-pehage.ads)
12715 @section @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads})
12716 @cindex @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads})
12717 @cindex Hash functions
12720 Provides a generator of static minimal perfect hash functions. No
12721 collisions occur and each item can be retrieved from the table in one
12722 probe (perfect property). The hash table size corresponds to the exact
12723 size of the key set and no larger (minimal property). The key set has to
12724 be know in advance (static property). The hash functions are also order
12725 preserving. If w2 is inserted after w1 in the generator, their
12726 hashcode are in the same order. These hashing functions are very
12727 convenient for use with realtime applications.
12729 @node GNAT.Regexp (g-regexp.ads)
12730 @section @code{GNAT.Regexp} (@file{g-regexp.ads})
12731 @cindex @code{GNAT.Regexp} (@file{g-regexp.ads})
12732 @cindex Regular expressions
12733 @cindex Pattern matching
12736 A simple implementation of regular expressions, using a subset of regular
12737 expression syntax copied from familiar Unix style utilities. This is the
12738 simples of the three pattern matching packages provided, and is particularly
12739 suitable for ``file globbing'' applications.
12741 @node GNAT.Registry (g-regist.ads)
12742 @section @code{GNAT.Registry} (@file{g-regist.ads})
12743 @cindex @code{GNAT.Registry} (@file{g-regist.ads})
12744 @cindex Windows Registry
12747 This is a high level binding to the Windows registry. It is possible to
12748 do simple things like reading a key value, creating a new key. For full
12749 registry API, but at a lower level of abstraction, refer to the Win32.Winreg
12750 package provided with the Win32Ada binding
12752 @node GNAT.Regpat (g-regpat.ads)
12753 @section @code{GNAT.Regpat} (@file{g-regpat.ads})
12754 @cindex @code{GNAT.Regpat} (@file{g-regpat.ads})
12755 @cindex Regular expressions
12756 @cindex Pattern matching
12759 A complete implementation of Unix-style regular expression matching, copied
12760 from the original V7 style regular expression library written in C by
12761 Henry Spencer (and binary compatible with this C library).
12763 @node GNAT.Secondary_Stack_Info (g-sestin.ads)
12764 @section @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads})
12765 @cindex @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads})
12766 @cindex Secondary Stack Info
12769 Provide the capability to query the high water mark of the current task's
12772 @node GNAT.Semaphores (g-semaph.ads)
12773 @section @code{GNAT.Semaphores} (@file{g-semaph.ads})
12774 @cindex @code{GNAT.Semaphores} (@file{g-semaph.ads})
12778 Provides classic counting and binary semaphores using protected types.
12780 @node GNAT.Signals (g-signal.ads)
12781 @section @code{GNAT.Signals} (@file{g-signal.ads})
12782 @cindex @code{GNAT.Signals} (@file{g-signal.ads})
12786 Provides the ability to manipulate the blocked status of signals on supported
12789 @node GNAT.Sockets (g-socket.ads)
12790 @section @code{GNAT.Sockets} (@file{g-socket.ads})
12791 @cindex @code{GNAT.Sockets} (@file{g-socket.ads})
12795 A high level and portable interface to develop sockets based applications.
12796 This package is based on the sockets thin binding found in
12797 @code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented
12798 on all native GNAT ports except for OpenVMS@. It is not implemented
12799 for the LynxOS@ cross port.
12801 @node GNAT.Source_Info (g-souinf.ads)
12802 @section @code{GNAT.Source_Info} (@file{g-souinf.ads})
12803 @cindex @code{GNAT.Source_Info} (@file{g-souinf.ads})
12804 @cindex Source Information
12807 Provides subprograms that give access to source code information known at
12808 compile time, such as the current file name and line number.
12810 @node GNAT.Spell_Checker (g-speche.ads)
12811 @section @code{GNAT.Spell_Checker} (@file{g-speche.ads})
12812 @cindex @code{GNAT.Spell_Checker} (@file{g-speche.ads})
12813 @cindex Spell checking
12816 Provides a function for determining whether one string is a plausible
12817 near misspelling of another string.
12819 @node GNAT.Spitbol.Patterns (g-spipat.ads)
12820 @section @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads})
12821 @cindex @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads})
12822 @cindex SPITBOL pattern matching
12823 @cindex Pattern matching
12826 A complete implementation of SNOBOL4 style pattern matching. This is the
12827 most elaborate of the pattern matching packages provided. It fully duplicates
12828 the SNOBOL4 dynamic pattern construction and matching capabilities, using the
12829 efficient algorithm developed by Robert Dewar for the SPITBOL system.
12831 @node GNAT.Spitbol (g-spitbo.ads)
12832 @section @code{GNAT.Spitbol} (@file{g-spitbo.ads})
12833 @cindex @code{GNAT.Spitbol} (@file{g-spitbo.ads})
12834 @cindex SPITBOL interface
12837 The top level package of the collection of SPITBOL-style functionality, this
12838 package provides basic SNOBOL4 string manipulation functions, such as
12839 Pad, Reverse, Trim, Substr capability, as well as a generic table function
12840 useful for constructing arbitrary mappings from strings in the style of
12841 the SNOBOL4 TABLE function.
12843 @node GNAT.Spitbol.Table_Boolean (g-sptabo.ads)
12844 @section @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads})
12845 @cindex @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads})
12846 @cindex Sets of strings
12847 @cindex SPITBOL Tables
12850 A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
12851 for type @code{Standard.Boolean}, giving an implementation of sets of
12854 @node GNAT.Spitbol.Table_Integer (g-sptain.ads)
12855 @section @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads})
12856 @cindex @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads})
12857 @cindex Integer maps
12859 @cindex SPITBOL Tables
12862 A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
12863 for type @code{Standard.Integer}, giving an implementation of maps
12864 from string to integer values.
12866 @node GNAT.Spitbol.Table_VString (g-sptavs.ads)
12867 @section @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads})
12868 @cindex @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads})
12869 @cindex String maps
12871 @cindex SPITBOL Tables
12874 A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for
12875 a variable length string type, giving an implementation of general
12876 maps from strings to strings.
12878 @node GNAT.Strings (g-string.ads)
12879 @section @code{GNAT.Strings} (@file{g-string.ads})
12880 @cindex @code{GNAT.Strings} (@file{g-string.ads})
12883 Common String access types and related subprograms. Basically it
12884 defines a string access and an array of string access types.
12886 @node GNAT.String_Split (g-strspl.ads)
12887 @section @code{GNAT.String_Split} (@file{g-strspl.ads})
12888 @cindex @code{GNAT.String_Split} (@file{g-strspl.ads})
12889 @cindex String splitter
12892 Useful string manipulation routines: given a set of separators, split
12893 a string wherever the separators appear, and provide direct access
12894 to the resulting slices. This package is instantiated from
12895 @code{GNAT.Array_Split}.
12897 @node GNAT.UTF_32 (g-utf_32.ads)
12898 @section @code{GNAT.UTF_32} (@file{g-table.ads})
12899 @cindex @code{GNAT.UTF_32} (@file{g-table.ads})
12900 @cindex Wide character codes
12903 This is a package intended to be used in conjunction with the
12904 @code{Wide_Character} type in Ada 95 and the
12905 @code{Wide_Wide_Character} type in Ada 2005 (available
12906 in @code{GNAT} in Ada 2005 mode). This package contains
12907 Unicode categorization routines, as well as lexical
12908 categorization routines corresponding to the Ada 2005
12909 lexical rules for identifiers and strings, and also a
12910 lower case to upper case fold routine corresponding to
12911 the Ada 2005 rules for identifier equivalence.
12913 @node GNAT.Table (g-table.ads)
12914 @section @code{GNAT.Table} (@file{g-table.ads})
12915 @cindex @code{GNAT.Table} (@file{g-table.ads})
12916 @cindex Table implementation
12917 @cindex Arrays, extendable
12920 A generic package providing a single dimension array abstraction where the
12921 length of the array can be dynamically modified.
12924 This package provides a facility similar to that of @code{GNAT.Dynamic_Tables},
12925 except that this package declares a single instance of the table type,
12926 while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be
12927 used to define dynamic instances of the table.
12929 @node GNAT.Task_Lock (g-tasloc.ads)
12930 @section @code{GNAT.Task_Lock} (@file{g-tasloc.ads})
12931 @cindex @code{GNAT.Task_Lock} (@file{g-tasloc.ads})
12932 @cindex Task synchronization
12933 @cindex Task locking
12937 A very simple facility for locking and unlocking sections of code using a
12938 single global task lock. Appropriate for use in situations where contention
12939 between tasks is very rarely expected.
12941 @node GNAT.Threads (g-thread.ads)
12942 @section @code{GNAT.Threads} (@file{g-thread.ads})
12943 @cindex @code{GNAT.Threads} (@file{g-thread.ads})
12944 @cindex Foreign threads
12945 @cindex Threads, foreign
12948 Provides facilities for creating and destroying threads with explicit calls.
12949 These threads are known to the GNAT run-time system. These subprograms are
12950 exported C-convention procedures intended to be called from foreign code.
12951 By using these primitives rather than directly calling operating systems
12952 routines, compatibility with the Ada tasking run-time is provided.
12954 @node GNAT.Traceback (g-traceb.ads)
12955 @section @code{GNAT.Traceback} (@file{g-traceb.ads})
12956 @cindex @code{GNAT.Traceback} (@file{g-traceb.ads})
12957 @cindex Trace back facilities
12960 Provides a facility for obtaining non-symbolic traceback information, useful
12961 in various debugging situations.
12963 @node GNAT.Traceback.Symbolic (g-trasym.ads)
12964 @section @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads})
12965 @cindex @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads})
12966 @cindex Trace back facilities
12969 Provides symbolic traceback information that includes the subprogram
12970 name and line number information.
12972 @node GNAT.Wide_String_Split (g-wistsp.ads)
12973 @section @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads})
12974 @cindex @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads})
12975 @cindex Wide_String splitter
12978 Useful wide string manipulation routines: given a set of separators, split
12979 a wide string wherever the separators appear, and provide direct access
12980 to the resulting slices. This package is instantiated from
12981 @code{GNAT.Array_Split}.
12983 @node GNAT.Wide_Wide_String_Split (g-zistsp.ads)
12984 @section @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads})
12985 @cindex @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads})
12986 @cindex Wide_Wide_String splitter
12989 Useful wide wide string manipulation routines: given a set of separators, split
12990 a wide wide string wherever the separators appear, and provide direct access
12991 to the resulting slices. This package is instantiated from
12992 @code{GNAT.Array_Split}.
12994 @node Interfaces.C.Extensions (i-cexten.ads)
12995 @section @code{Interfaces.C.Extensions} (@file{i-cexten.ads})
12996 @cindex @code{Interfaces.C.Extensions} (@file{i-cexten.ads})
12999 This package contains additional C-related definitions, intended
13000 for use with either manually or automatically generated bindings
13003 @node Interfaces.C.Streams (i-cstrea.ads)
13004 @section @code{Interfaces.C.Streams} (@file{i-cstrea.ads})
13005 @cindex @code{Interfaces.C.Streams} (@file{i-cstrea.ads})
13006 @cindex C streams, interfacing
13009 This package is a binding for the most commonly used operations
13012 @node Interfaces.CPP (i-cpp.ads)
13013 @section @code{Interfaces.CPP} (@file{i-cpp.ads})
13014 @cindex @code{Interfaces.CPP} (@file{i-cpp.ads})
13015 @cindex C++ interfacing
13016 @cindex Interfacing, to C++
13019 This package provides facilities for use in interfacing to C++. It
13020 is primarily intended to be used in connection with automated tools
13021 for the generation of C++ interfaces.
13023 @node Interfaces.Os2lib (i-os2lib.ads)
13024 @section @code{Interfaces.Os2lib} (@file{i-os2lib.ads})
13025 @cindex @code{Interfaces.Os2lib} (@file{i-os2lib.ads})
13026 @cindex Interfacing, to OS/2
13027 @cindex OS/2 interfacing
13030 This package provides interface definitions to the OS/2 library.
13031 It is a thin binding which is a direct translation of the
13032 various @file{<bse@.h>} files.
13034 @node Interfaces.Os2lib.Errors (i-os2err.ads)
13035 @section @code{Interfaces.Os2lib.Errors} (@file{i-os2err.ads})
13036 @cindex @code{Interfaces.Os2lib.Errors} (@file{i-os2err.ads})
13037 @cindex OS/2 Error codes
13038 @cindex Interfacing, to OS/2
13039 @cindex OS/2 interfacing
13042 This package provides definitions of the OS/2 error codes.
13044 @node Interfaces.Os2lib.Synchronization (i-os2syn.ads)
13045 @section @code{Interfaces.Os2lib.Synchronization} (@file{i-os2syn.ads})
13046 @cindex @code{Interfaces.Os2lib.Synchronization} (@file{i-os2syn.ads})
13047 @cindex Interfacing, to OS/2
13048 @cindex Synchronization, OS/2
13049 @cindex OS/2 synchronization primitives
13052 This is a child package that provides definitions for interfacing
13053 to the @code{OS/2} synchronization primitives.
13055 @node Interfaces.Os2lib.Threads (i-os2thr.ads)
13056 @section @code{Interfaces.Os2lib.Threads} (@file{i-os2thr.ads})
13057 @cindex @code{Interfaces.Os2lib.Threads} (@file{i-os2thr.ads})
13058 @cindex Interfacing, to OS/2
13059 @cindex Thread control, OS/2
13060 @cindex OS/2 thread interfacing
13063 This is a child package that provides definitions for interfacing
13064 to the @code{OS/2} thread primitives.
13066 @node Interfaces.Packed_Decimal (i-pacdec.ads)
13067 @section @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads})
13068 @cindex @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads})
13069 @cindex IBM Packed Format
13070 @cindex Packed Decimal
13073 This package provides a set of routines for conversions to and
13074 from a packed decimal format compatible with that used on IBM
13077 @node Interfaces.VxWorks (i-vxwork.ads)
13078 @section @code{Interfaces.VxWorks} (@file{i-vxwork.ads})
13079 @cindex @code{Interfaces.VxWorks} (@file{i-vxwork.ads})
13080 @cindex Interfacing to VxWorks
13081 @cindex VxWorks, interfacing
13084 This package provides a limited binding to the VxWorks API.
13085 In particular, it interfaces with the
13086 VxWorks hardware interrupt facilities.
13088 @node Interfaces.VxWorks.IO (i-vxwoio.ads)
13089 @section @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads})
13090 @cindex @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads})
13091 @cindex Interfacing to VxWorks' I/O
13092 @cindex VxWorks, I/O interfacing
13093 @cindex VxWorks, Get_Immediate
13094 @cindex Get_Immediate, VxWorks
13097 This package provides a binding to the ioctl (IO/Control)
13098 function of VxWorks, defining a set of option values and
13099 function codes. A particular use of this package is
13100 to enable the use of Get_Immediate under VxWorks.
13102 @node System.Address_Image (s-addima.ads)
13103 @section @code{System.Address_Image} (@file{s-addima.ads})
13104 @cindex @code{System.Address_Image} (@file{s-addima.ads})
13105 @cindex Address image
13106 @cindex Image, of an address
13109 This function provides a useful debugging
13110 function that gives an (implementation dependent)
13111 string which identifies an address.
13113 @node System.Assertions (s-assert.ads)
13114 @section @code{System.Assertions} (@file{s-assert.ads})
13115 @cindex @code{System.Assertions} (@file{s-assert.ads})
13117 @cindex Assert_Failure, exception
13120 This package provides the declaration of the exception raised
13121 by an run-time assertion failure, as well as the routine that
13122 is used internally to raise this assertion.
13124 @node System.Memory (s-memory.ads)
13125 @section @code{System.Memory} (@file{s-memory.ads})
13126 @cindex @code{System.Memory} (@file{s-memory.ads})
13127 @cindex Memory allocation
13130 This package provides the interface to the low level routines used
13131 by the generated code for allocation and freeing storage for the
13132 default storage pool (analogous to the C routines malloc and free.
13133 It also provides a reallocation interface analogous to the C routine
13134 realloc. The body of this unit may be modified to provide alternative
13135 allocation mechanisms for the default pool, and in addition, direct
13136 calls to this unit may be made for low level allocation uses (for
13137 example see the body of @code{GNAT.Tables}).
13139 @node System.Partition_Interface (s-parint.ads)
13140 @section @code{System.Partition_Interface} (@file{s-parint.ads})
13141 @cindex @code{System.Partition_Interface} (@file{s-parint.ads})
13142 @cindex Partition interfacing functions
13145 This package provides facilities for partition interfacing. It
13146 is used primarily in a distribution context when using Annex E
13149 @node System.Restrictions (s-restri.ads)
13150 @section @code{System.Restrictions} (@file{s-restri.ads})
13151 @cindex @code{System.Restrictions} (@file{s-restri.ads})
13152 @cindex Run-time restrictions access
13155 This package provides facilities for accessing at run-time
13156 the status of restrictions specified at compile time for
13157 the partition. Information is available both with regard
13158 to actual restrictions specified, and with regard to
13159 compiler determined information on which restrictions
13160 are violated by one or more packages in the partition.
13162 @node System.Rident (s-rident.ads)
13163 @section @code{System.Rident} (@file{s-rident.ads})
13164 @cindex @code{System.Rident} (@file{s-rident.ads})
13165 @cindex Restrictions definitions
13168 This package provides definitions of the restrictions
13169 identifiers supported by GNAT, and also the format of
13170 the restrictions provided in package System.Restrictions.
13171 It is not normally necessary to @code{with} this generic package
13172 since the necessary instantiation is included in
13173 package System.Restrictions.
13175 @node System.Task_Info (s-tasinf.ads)
13176 @section @code{System.Task_Info} (@file{s-tasinf.ads})
13177 @cindex @code{System.Task_Info} (@file{s-tasinf.ads})
13178 @cindex Task_Info pragma
13181 This package provides target dependent functionality that is used
13182 to support the @code{Task_Info} pragma
13184 @node System.Wch_Cnv (s-wchcnv.ads)
13185 @section @code{System.Wch_Cnv} (@file{s-wchcnv.ads})
13186 @cindex @code{System.Wch_Cnv} (@file{s-wchcnv.ads})
13187 @cindex Wide Character, Representation
13188 @cindex Wide String, Conversion
13189 @cindex Representation of wide characters
13192 This package provides routines for converting between
13193 wide and wide wide characters and a representation as a value of type
13194 @code{Standard.String}, using a specified wide character
13195 encoding method. It uses definitions in
13196 package @code{System.Wch_Con}.
13198 @node System.Wch_Con (s-wchcon.ads)
13199 @section @code{System.Wch_Con} (@file{s-wchcon.ads})
13200 @cindex @code{System.Wch_Con} (@file{s-wchcon.ads})
13203 This package provides definitions and descriptions of
13204 the various methods used for encoding wide characters
13205 in ordinary strings. These definitions are used by
13206 the package @code{System.Wch_Cnv}.
13208 @node Interfacing to Other Languages
13209 @chapter Interfacing to Other Languages
13211 The facilities in annex B of the Ada 95 Reference Manual are fully
13212 implemented in GNAT, and in addition, a full interface to C++ is
13216 * Interfacing to C::
13217 * Interfacing to C++::
13218 * Interfacing to COBOL::
13219 * Interfacing to Fortran::
13220 * Interfacing to non-GNAT Ada code::
13223 @node Interfacing to C
13224 @section Interfacing to C
13227 Interfacing to C with GNAT can use one of two approaches:
13231 The types in the package @code{Interfaces.C} may be used.
13233 Standard Ada types may be used directly. This may be less portable to
13234 other compilers, but will work on all GNAT compilers, which guarantee
13235 correspondence between the C and Ada types.
13239 Pragma @code{Convention C} may be applied to Ada types, but mostly has no
13240 effect, since this is the default. The following table shows the
13241 correspondence between Ada scalar types and the corresponding C types.
13246 @item Short_Integer
13248 @item Short_Short_Integer
13252 @item Long_Long_Integer
13260 @item Long_Long_Float
13261 This is the longest floating-point type supported by the hardware.
13265 Additionally, there are the following general correspondences between Ada
13269 Ada enumeration types map to C enumeration types directly if pragma
13270 @code{Convention C} is specified, which causes them to have int
13271 length. Without pragma @code{Convention C}, Ada enumeration types map to
13272 8, 16, or 32 bits (i.e.@: C types @code{signed char}, @code{short},
13273 @code{int}, respectively) depending on the number of values passed.
13274 This is the only case in which pragma @code{Convention C} affects the
13275 representation of an Ada type.
13278 Ada access types map to C pointers, except for the case of pointers to
13279 unconstrained types in Ada, which have no direct C equivalent.
13282 Ada arrays map directly to C arrays.
13285 Ada records map directly to C structures.
13288 Packed Ada records map to C structures where all members are bit fields
13289 of the length corresponding to the @code{@var{type}'Size} value in Ada.
13292 @node Interfacing to C++
13293 @section Interfacing to C++
13296 The interface to C++ makes use of the following pragmas, which are
13297 primarily intended to be constructed automatically using a binding generator
13298 tool, although it is possible to construct them by hand. No suitable binding
13299 generator tool is supplied with GNAT though.
13301 Using these pragmas it is possible to achieve complete
13302 inter-operability between Ada tagged types and C class definitions.
13303 See @ref{Implementation Defined Pragmas}, for more details.
13306 @item pragma CPP_Class ([Entity =>] @var{local_NAME})
13307 The argument denotes an entity in the current declarative region that is
13308 declared as a tagged or untagged record type. It indicates that the type
13309 corresponds to an externally declared C++ class type, and is to be laid
13310 out the same way that C++ would lay out the type.
13312 @item pragma CPP_Constructor ([Entity =>] @var{local_NAME})
13313 This pragma identifies an imported function (imported in the usual way
13314 with pragma @code{Import}) as corresponding to a C++ constructor.
13316 @item pragma CPP_Vtable @dots{}
13317 One @code{CPP_Vtable} pragma can be present for each component of type
13318 @code{CPP.Interfaces.Vtable_Ptr} in a record to which pragma @code{CPP_Class}
13322 @node Interfacing to COBOL
13323 @section Interfacing to COBOL
13326 Interfacing to COBOL is achieved as described in section B.4 of
13327 the Ada 95 reference manual.
13329 @node Interfacing to Fortran
13330 @section Interfacing to Fortran
13333 Interfacing to Fortran is achieved as described in section B.5 of the
13334 reference manual. The pragma @code{Convention Fortran}, applied to a
13335 multi-dimensional array causes the array to be stored in column-major
13336 order as required for convenient interface to Fortran.
13338 @node Interfacing to non-GNAT Ada code
13339 @section Interfacing to non-GNAT Ada code
13341 It is possible to specify the convention @code{Ada} in a pragma
13342 @code{Import} or pragma @code{Export}. However this refers to
13343 the calling conventions used by GNAT, which may or may not be
13344 similar enough to those used by some other Ada 83 or Ada 95
13345 compiler to allow interoperation.
13347 If arguments types are kept simple, and if the foreign compiler generally
13348 follows system calling conventions, then it may be possible to integrate
13349 files compiled by other Ada compilers, provided that the elaboration
13350 issues are adequately addressed (for example by eliminating the
13351 need for any load time elaboration).
13353 In particular, GNAT running on VMS is designed to
13354 be highly compatible with the DEC Ada 83 compiler, so this is one
13355 case in which it is possible to import foreign units of this type,
13356 provided that the data items passed are restricted to simple scalar
13357 values or simple record types without variants, or simple array
13358 types with fixed bounds.
13360 @node Specialized Needs Annexes
13361 @chapter Specialized Needs Annexes
13364 Ada 95 defines a number of specialized needs annexes, which are not
13365 required in all implementations. However, as described in this chapter,
13366 GNAT implements all of these special needs annexes:
13369 @item Systems Programming (Annex C)
13370 The Systems Programming Annex is fully implemented.
13372 @item Real-Time Systems (Annex D)
13373 The Real-Time Systems Annex is fully implemented.
13375 @item Distributed Systems (Annex E)
13376 Stub generation is fully implemented in the GNAT compiler. In addition,
13377 a complete compatible PCS is available as part of the GLADE system,
13378 a separate product. When the two
13379 products are used in conjunction, this annex is fully implemented.
13381 @item Information Systems (Annex F)
13382 The Information Systems annex is fully implemented.
13384 @item Numerics (Annex G)
13385 The Numerics Annex is fully implemented.
13387 @item Safety and Security (Annex H)
13388 The Safety and Security annex is fully implemented.
13391 @node Implementation of Specific Ada Features
13392 @chapter Implementation of Specific Ada Features
13395 This chapter describes the GNAT implementation of several Ada language
13399 * Machine Code Insertions::
13400 * GNAT Implementation of Tasking::
13401 * GNAT Implementation of Shared Passive Packages::
13402 * Code Generation for Array Aggregates::
13403 * The Size of Discriminated Records with Default Discriminants::
13406 @node Machine Code Insertions
13407 @section Machine Code Insertions
13410 Package @code{Machine_Code} provides machine code support as described
13411 in the Ada 95 Reference Manual in two separate forms:
13414 Machine code statements, consisting of qualified expressions that
13415 fit the requirements of RM section 13.8.
13417 An intrinsic callable procedure, providing an alternative mechanism of
13418 including machine instructions in a subprogram.
13422 The two features are similar, and both are closely related to the mechanism
13423 provided by the asm instruction in the GNU C compiler. Full understanding
13424 and use of the facilities in this package requires understanding the asm
13425 instruction as described in @cite{Using the GNU Compiler Collection (GCC)}
13426 by Richard Stallman. The relevant section is titled ``Extensions to the C
13427 Language Family'' -> ``Assembler Instructions with C Expression Operands''.
13429 Calls to the function @code{Asm} and the procedure @code{Asm} have identical
13430 semantic restrictions and effects as described below. Both are provided so
13431 that the procedure call can be used as a statement, and the function call
13432 can be used to form a code_statement.
13434 The first example given in the GCC documentation is the C @code{asm}
13437 asm ("fsinx %1 %0" : "=f" (result) : "f" (angle));
13441 The equivalent can be written for GNAT as:
13443 @smallexample @c ada
13444 Asm ("fsinx %1 %0",
13445 My_Float'Asm_Output ("=f", result),
13446 My_Float'Asm_Input ("f", angle));
13450 The first argument to @code{Asm} is the assembler template, and is
13451 identical to what is used in GNU C@. This string must be a static
13452 expression. The second argument is the output operand list. It is
13453 either a single @code{Asm_Output} attribute reference, or a list of such
13454 references enclosed in parentheses (technically an array aggregate of
13457 The @code{Asm_Output} attribute denotes a function that takes two
13458 parameters. The first is a string, the second is the name of a variable
13459 of the type designated by the attribute prefix. The first (string)
13460 argument is required to be a static expression and designates the
13461 constraint for the parameter (e.g.@: what kind of register is
13462 required). The second argument is the variable to be updated with the
13463 result. The possible values for constraint are the same as those used in
13464 the RTL, and are dependent on the configuration file used to build the
13465 GCC back end. If there are no output operands, then this argument may
13466 either be omitted, or explicitly given as @code{No_Output_Operands}.
13468 The second argument of @code{@var{my_float}'Asm_Output} functions as
13469 though it were an @code{out} parameter, which is a little curious, but
13470 all names have the form of expressions, so there is no syntactic
13471 irregularity, even though normally functions would not be permitted
13472 @code{out} parameters. The third argument is the list of input
13473 operands. It is either a single @code{Asm_Input} attribute reference, or
13474 a list of such references enclosed in parentheses (technically an array
13475 aggregate of such references).
13477 The @code{Asm_Input} attribute denotes a function that takes two
13478 parameters. The first is a string, the second is an expression of the
13479 type designated by the prefix. The first (string) argument is required
13480 to be a static expression, and is the constraint for the parameter,
13481 (e.g.@: what kind of register is required). The second argument is the
13482 value to be used as the input argument. The possible values for the
13483 constant are the same as those used in the RTL, and are dependent on
13484 the configuration file used to built the GCC back end.
13486 If there are no input operands, this argument may either be omitted, or
13487 explicitly given as @code{No_Input_Operands}. The fourth argument, not
13488 present in the above example, is a list of register names, called the
13489 @dfn{clobber} argument. This argument, if given, must be a static string
13490 expression, and is a space or comma separated list of names of registers
13491 that must be considered destroyed as a result of the @code{Asm} call. If
13492 this argument is the null string (the default value), then the code
13493 generator assumes that no additional registers are destroyed.
13495 The fifth argument, not present in the above example, called the
13496 @dfn{volatile} argument, is by default @code{False}. It can be set to
13497 the literal value @code{True} to indicate to the code generator that all
13498 optimizations with respect to the instruction specified should be
13499 suppressed, and that in particular, for an instruction that has outputs,
13500 the instruction will still be generated, even if none of the outputs are
13501 used. See the full description in the GCC manual for further details.
13503 The @code{Asm} subprograms may be used in two ways. First the procedure
13504 forms can be used anywhere a procedure call would be valid, and
13505 correspond to what the RM calls ``intrinsic'' routines. Such calls can
13506 be used to intersperse machine instructions with other Ada statements.
13507 Second, the function forms, which return a dummy value of the limited
13508 private type @code{Asm_Insn}, can be used in code statements, and indeed
13509 this is the only context where such calls are allowed. Code statements
13510 appear as aggregates of the form:
13512 @smallexample @c ada
13513 Asm_Insn'(Asm (@dots{}));
13514 Asm_Insn'(Asm_Volatile (@dots{}));
13518 In accordance with RM rules, such code statements are allowed only
13519 within subprograms whose entire body consists of such statements. It is
13520 not permissible to intermix such statements with other Ada statements.
13522 Typically the form using intrinsic procedure calls is more convenient
13523 and more flexible. The code statement form is provided to meet the RM
13524 suggestion that such a facility should be made available. The following
13525 is the exact syntax of the call to @code{Asm}. As usual, if named notation
13526 is used, the arguments may be given in arbitrary order, following the
13527 normal rules for use of positional and named arguments)
13531 [Template =>] static_string_EXPRESSION
13532 [,[Outputs =>] OUTPUT_OPERAND_LIST ]
13533 [,[Inputs =>] INPUT_OPERAND_LIST ]
13534 [,[Clobber =>] static_string_EXPRESSION ]
13535 [,[Volatile =>] static_boolean_EXPRESSION] )
13537 OUTPUT_OPERAND_LIST ::=
13538 [PREFIX.]No_Output_Operands
13539 | OUTPUT_OPERAND_ATTRIBUTE
13540 | (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@})
13542 OUTPUT_OPERAND_ATTRIBUTE ::=
13543 SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME)
13545 INPUT_OPERAND_LIST ::=
13546 [PREFIX.]No_Input_Operands
13547 | INPUT_OPERAND_ATTRIBUTE
13548 | (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@})
13550 INPUT_OPERAND_ATTRIBUTE ::=
13551 SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION)
13555 The identifiers @code{No_Input_Operands} and @code{No_Output_Operands}
13556 are declared in the package @code{Machine_Code} and must be referenced
13557 according to normal visibility rules. In particular if there is no
13558 @code{use} clause for this package, then appropriate package name
13559 qualification is required.
13561 @node GNAT Implementation of Tasking
13562 @section GNAT Implementation of Tasking
13565 This chapter outlines the basic GNAT approach to tasking (in particular,
13566 a multi-layered library for portability) and discusses issues related
13567 to compliance with the Real-Time Systems Annex.
13570 * Mapping Ada Tasks onto the Underlying Kernel Threads::
13571 * Ensuring Compliance with the Real-Time Annex::
13574 @node Mapping Ada Tasks onto the Underlying Kernel Threads
13575 @subsection Mapping Ada Tasks onto the Underlying Kernel Threads
13578 GNAT's run-time support comprises two layers:
13581 @item GNARL (GNAT Run-time Layer)
13582 @item GNULL (GNAT Low-level Library)
13586 In GNAT, Ada's tasking services rely on a platform and OS independent
13587 layer known as GNARL@. This code is responsible for implementing the
13588 correct semantics of Ada's task creation, rendezvous, protected
13591 GNARL decomposes Ada's tasking semantics into simpler lower level
13592 operations such as create a thread, set the priority of a thread,
13593 yield, create a lock, lock/unlock, etc. The spec for these low-level
13594 operations constitutes GNULLI, the GNULL Interface. This interface is
13595 directly inspired from the POSIX real-time API@.
13597 If the underlying executive or OS implements the POSIX standard
13598 faithfully, the GNULL Interface maps as is to the services offered by
13599 the underlying kernel. Otherwise, some target dependent glue code maps
13600 the services offered by the underlying kernel to the semantics expected
13603 Whatever the underlying OS (VxWorks, UNIX, OS/2, Windows NT, etc.) the
13604 key point is that each Ada task is mapped on a thread in the underlying
13605 kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task.
13607 In addition Ada task priorities map onto the underlying thread priorities.
13608 Mapping Ada tasks onto the underlying kernel threads has several advantages:
13612 The underlying scheduler is used to schedule the Ada tasks. This
13613 makes Ada tasks as efficient as kernel threads from a scheduling
13617 Interaction with code written in C containing threads is eased
13618 since at the lowest level Ada tasks and C threads map onto the same
13619 underlying kernel concept.
13622 When an Ada task is blocked during I/O the remaining Ada tasks are
13626 On multiprocessor systems Ada tasks can execute in parallel.
13630 Some threads libraries offer a mechanism to fork a new process, with the
13631 child process duplicating the threads from the parent.
13633 support this functionality when the parent contains more than one task.
13634 @cindex Forking a new process
13636 @node Ensuring Compliance with the Real-Time Annex
13637 @subsection Ensuring Compliance with the Real-Time Annex
13638 @cindex Real-Time Systems Annex compliance
13641 Although mapping Ada tasks onto
13642 the underlying threads has significant advantages, it does create some
13643 complications when it comes to respecting the scheduling semantics
13644 specified in the real-time annex (Annex D).
13646 For instance the Annex D requirement for the @code{FIFO_Within_Priorities}
13647 scheduling policy states:
13650 @emph{When the active priority of a ready task that is not running
13651 changes, or the setting of its base priority takes effect, the
13652 task is removed from the ready queue for its old active priority
13653 and is added at the tail of the ready queue for its new active
13654 priority, except in the case where the active priority is lowered
13655 due to the loss of inherited priority, in which case the task is
13656 added at the head of the ready queue for its new active priority.}
13660 While most kernels do put tasks at the end of the priority queue when
13661 a task changes its priority, (which respects the main
13662 FIFO_Within_Priorities requirement), almost none keep a thread at the
13663 beginning of its priority queue when its priority drops from the loss
13664 of inherited priority.
13666 As a result most vendors have provided incomplete Annex D implementations.
13668 The GNAT run-time, has a nice cooperative solution to this problem
13669 which ensures that accurate FIFO_Within_Priorities semantics are
13672 The principle is as follows. When an Ada task T is about to start
13673 running, it checks whether some other Ada task R with the same
13674 priority as T has been suspended due to the loss of priority
13675 inheritance. If this is the case, T yields and is placed at the end of
13676 its priority queue. When R arrives at the front of the queue it
13679 Note that this simple scheme preserves the relative order of the tasks
13680 that were ready to execute in the priority queue where R has been
13683 @node GNAT Implementation of Shared Passive Packages
13684 @section GNAT Implementation of Shared Passive Packages
13685 @cindex Shared passive packages
13688 GNAT fully implements the pragma @code{Shared_Passive} for
13689 @cindex pragma @code{Shared_Passive}
13690 the purpose of designating shared passive packages.
13691 This allows the use of passive partitions in the
13692 context described in the Ada Reference Manual; i.e. for communication
13693 between separate partitions of a distributed application using the
13694 features in Annex E.
13696 @cindex Distribution Systems Annex
13698 However, the implementation approach used by GNAT provides for more
13699 extensive usage as follows:
13702 @item Communication between separate programs
13704 This allows separate programs to access the data in passive
13705 partitions, using protected objects for synchronization where
13706 needed. The only requirement is that the two programs have a
13707 common shared file system. It is even possible for programs
13708 running on different machines with different architectures
13709 (e.g. different endianness) to communicate via the data in
13710 a passive partition.
13712 @item Persistence between program runs
13714 The data in a passive package can persist from one run of a
13715 program to another, so that a later program sees the final
13716 values stored by a previous run of the same program.
13721 The implementation approach used is to store the data in files. A
13722 separate stream file is created for each object in the package, and
13723 an access to an object causes the corresponding file to be read or
13726 The environment variable @code{SHARED_MEMORY_DIRECTORY} should be
13727 @cindex @code{SHARED_MEMORY_DIRECTORY} environment variable
13728 set to the directory to be used for these files.
13729 The files in this directory
13730 have names that correspond to their fully qualified names. For
13731 example, if we have the package
13733 @smallexample @c ada
13735 pragma Shared_Passive (X);
13742 and the environment variable is set to @code{/stemp/}, then the files created
13743 will have the names:
13751 These files are created when a value is initially written to the object, and
13752 the files are retained until manually deleted. This provides the persistence
13753 semantics. If no file exists, it means that no partition has assigned a value
13754 to the variable; in this case the initial value declared in the package
13755 will be used. This model ensures that there are no issues in synchronizing
13756 the elaboration process, since elaboration of passive packages elaborates the
13757 initial values, but does not create the files.
13759 The files are written using normal @code{Stream_IO} access.
13760 If you want to be able
13761 to communicate between programs or partitions running on different
13762 architectures, then you should use the XDR versions of the stream attribute
13763 routines, since these are architecture independent.
13765 If active synchronization is required for access to the variables in the
13766 shared passive package, then as described in the Ada Reference Manual, the
13767 package may contain protected objects used for this purpose. In this case
13768 a lock file (whose name is @file{___lock} (three underscores)
13769 is created in the shared memory directory.
13770 @cindex @file{___lock} file (for shared passive packages)
13771 This is used to provide the required locking
13772 semantics for proper protected object synchronization.
13774 As of January 2003, GNAT supports shared passive packages on all platforms
13775 except for OpenVMS.
13777 @node Code Generation for Array Aggregates
13778 @section Code Generation for Array Aggregates
13781 * Static constant aggregates with static bounds::
13782 * Constant aggregates with an unconstrained nominal types::
13783 * Aggregates with static bounds::
13784 * Aggregates with non-static bounds::
13785 * Aggregates in assignment statements::
13789 Aggregate have a rich syntax and allow the user to specify the values of
13790 complex data structures by means of a single construct. As a result, the
13791 code generated for aggregates can be quite complex and involve loops, case
13792 statements and multiple assignments. In the simplest cases, however, the
13793 compiler will recognize aggregates whose components and constraints are
13794 fully static, and in those cases the compiler will generate little or no
13795 executable code. The following is an outline of the code that GNAT generates
13796 for various aggregate constructs. For further details, the user will find it
13797 useful to examine the output produced by the -gnatG flag to see the expanded
13798 source that is input to the code generator. The user will also want to examine
13799 the assembly code generated at various levels of optimization.
13801 The code generated for aggregates depends on the context, the component values,
13802 and the type. In the context of an object declaration the code generated is
13803 generally simpler than in the case of an assignment. As a general rule, static
13804 component values and static subtypes also lead to simpler code.
13806 @node Static constant aggregates with static bounds
13807 @subsection Static constant aggregates with static bounds
13810 For the declarations:
13811 @smallexample @c ada
13812 type One_Dim is array (1..10) of integer;
13813 ar0 : constant One_Dim := ( 1, 2, 3, 4, 5, 6, 7, 8, 9, 0);
13817 GNAT generates no executable code: the constant ar0 is placed in static memory.
13818 The same is true for constant aggregates with named associations:
13820 @smallexample @c ada
13821 Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1=> 1);
13822 Cr3 : constant One_Dim := (others => 7777);
13826 The same is true for multidimensional constant arrays such as:
13828 @smallexample @c ada
13829 type two_dim is array (1..3, 1..3) of integer;
13830 Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1));
13834 The same is true for arrays of one-dimensional arrays: the following are
13837 @smallexample @c ada
13838 type ar1b is array (1..3) of boolean;
13839 type ar_ar is array (1..3) of ar1b;
13840 None : constant ar1b := (others => false); -- fully static
13841 None2 : constant ar_ar := (1..3 => None); -- fully static
13845 However, for multidimensional aggregates with named associations, GNAT will
13846 generate assignments and loops, even if all associations are static. The
13847 following two declarations generate a loop for the first dimension, and
13848 individual component assignments for the second dimension:
13850 @smallexample @c ada
13851 Zero1: constant two_dim := (1..3 => (1..3 => 0));
13852 Zero2: constant two_dim := (others => (others => 0));
13855 @node Constant aggregates with an unconstrained nominal types
13856 @subsection Constant aggregates with an unconstrained nominal types
13859 In such cases the aggregate itself establishes the subtype, so that
13860 associations with @code{others} cannot be used. GNAT determines the
13861 bounds for the actual subtype of the aggregate, and allocates the
13862 aggregate statically as well. No code is generated for the following:
13864 @smallexample @c ada
13865 type One_Unc is array (natural range <>) of integer;
13866 Cr_Unc : constant One_Unc := (12,24,36);
13869 @node Aggregates with static bounds
13870 @subsection Aggregates with static bounds
13873 In all previous examples the aggregate was the initial (and immutable) value
13874 of a constant. If the aggregate initializes a variable, then code is generated
13875 for it as a combination of individual assignments and loops over the target
13876 object. The declarations
13878 @smallexample @c ada
13879 Cr_Var1 : One_Dim := (2, 5, 7, 11);
13880 Cr_Var2 : One_Dim := (others > -1);
13884 generate the equivalent of
13886 @smallexample @c ada
13892 for I in Cr_Var2'range loop
13893 Cr_Var2 (I) := =-1;
13897 @node Aggregates with non-static bounds
13898 @subsection Aggregates with non-static bounds
13901 If the bounds of the aggregate are not statically compatible with the bounds
13902 of the nominal subtype of the target, then constraint checks have to be
13903 generated on the bounds. For a multidimensional array, constraint checks may
13904 have to be applied to sub-arrays individually, if they do not have statically
13905 compatible subtypes.
13907 @node Aggregates in assignment statements
13908 @subsection Aggregates in assignment statements
13911 In general, aggregate assignment requires the construction of a temporary,
13912 and a copy from the temporary to the target of the assignment. This is because
13913 it is not always possible to convert the assignment into a series of individual
13914 component assignments. For example, consider the simple case:
13916 @smallexample @c ada
13921 This cannot be converted into:
13923 @smallexample @c ada
13929 So the aggregate has to be built first in a separate location, and then
13930 copied into the target. GNAT recognizes simple cases where this intermediate
13931 step is not required, and the assignments can be performed in place, directly
13932 into the target. The following sufficient criteria are applied:
13936 The bounds of the aggregate are static, and the associations are static.
13938 The components of the aggregate are static constants, names of
13939 simple variables that are not renamings, or expressions not involving
13940 indexed components whose operands obey these rules.
13944 If any of these conditions are violated, the aggregate will be built in
13945 a temporary (created either by the front-end or the code generator) and then
13946 that temporary will be copied onto the target.
13949 @node The Size of Discriminated Records with Default Discriminants
13950 @section The Size of Discriminated Records with Default Discriminants
13953 If a discriminated type @code{T} has discriminants with default values, it is
13954 possible to declare an object of this type without providing an explicit
13957 @smallexample @c ada
13959 type Size is range 1..100;
13961 type Rec (D : Size := 15) is record
13962 Name : String (1..D);
13970 Such an object is said to be @emph{unconstrained}.
13971 The discriminant of the object
13972 can be modified by a full assignment to the object, as long as it preserves the
13973 relation between the value of the discriminant, and the value of the components
13976 @smallexample @c ada
13978 Word := (3, "yes");
13980 Word := (5, "maybe");
13982 Word := (5, "no"); -- raises Constraint_Error
13987 In order to support this behavior efficiently, an unconstrained object is
13988 given the maximum size that any value of the type requires. In the case
13989 above, @code{Word} has storage for the discriminant and for
13990 a @code{String} of length 100.
13991 It is important to note that unconstrained objects do not require dynamic
13992 allocation. It would be an improper implementation to place on the heap those
13993 components whose size depends on discriminants. (This improper implementation
13994 was used by some Ada83 compilers, where the @code{Name} component above
13996 been stored as a pointer to a dynamic string). Following the principle that
13997 dynamic storage management should never be introduced implicitly,
13998 an Ada95 compiler should reserve the full size for an unconstrained declared
13999 object, and place it on the stack.
14001 This maximum size approach
14002 has been a source of surprise to some users, who expect the default
14003 values of the discriminants to determine the size reserved for an
14004 unconstrained object: ``If the default is 15, why should the object occupy
14006 The answer, of course, is that the discriminant may be later modified,
14007 and its full range of values must be taken into account. This is why the
14012 type Rec (D : Positive := 15) is record
14013 Name : String (1..D);
14021 is flagged by the compiler with a warning:
14022 an attempt to create @code{Too_Large} will raise @code{Storage_Error},
14023 because the required size includes @code{Positive'Last}
14024 bytes. As the first example indicates, the proper approach is to declare an
14025 index type of ``reasonable'' range so that unconstrained objects are not too
14028 One final wrinkle: if the object is declared to be @code{aliased}, or if it is
14029 created in the heap by means of an allocator, then it is @emph{not}
14031 it is constrained by the default values of the discriminants, and those values
14032 cannot be modified by full assignment. This is because in the presence of
14033 aliasing all views of the object (which may be manipulated by different tasks,
14034 say) must be consistent, so it is imperative that the object, once created,
14040 @node Project File Reference
14041 @chapter Project File Reference
14044 This chapter describes the syntax and semantics of project files.
14045 Project files specify the options to be used when building a system.
14046 Project files can specify global settings for all tools,
14047 as well as tool-specific settings.
14048 See the chapter on project files in the GNAT Users guide for examples of use.
14052 * Lexical Elements::
14054 * Empty declarations::
14055 * Typed string declarations::
14059 * Project Attributes::
14060 * Attribute References::
14061 * External Values::
14062 * Case Construction::
14064 * Package Renamings::
14066 * Project Extensions::
14067 * Project File Elaboration::
14070 @node Reserved Words
14071 @section Reserved Words
14074 All Ada95 reserved words are reserved in project files, and cannot be used
14075 as variable names or project names. In addition, the following are
14076 also reserved in project files:
14079 @item @code{extends}
14081 @item @code{external}
14083 @item @code{project}
14087 @node Lexical Elements
14088 @section Lexical Elements
14091 Rules for identifiers are the same as in Ada95. Identifiers
14092 are case-insensitive. Strings are case sensitive, except where noted.
14093 Comments have the same form as in Ada95.
14103 simple_name @{. simple_name@}
14107 @section Declarations
14110 Declarations introduce new entities that denote types, variables, attributes,
14111 and packages. Some declarations can only appear immediately within a project
14112 declaration. Others can appear within a project or within a package.
14116 declarative_item ::=
14117 simple_declarative_item |
14118 typed_string_declaration |
14119 package_declaration
14121 simple_declarative_item ::=
14122 variable_declaration |
14123 typed_variable_declaration |
14124 attribute_declaration |
14125 case_construction |
14129 @node Empty declarations
14130 @section Empty declarations
14133 empty_declaration ::=
14137 An empty declaration is allowed anywhere a declaration is allowed.
14140 @node Typed string declarations
14141 @section Typed string declarations
14144 Typed strings are sequences of string literals. Typed strings are the only
14145 named types in project files. They are used in case constructions, where they
14146 provide support for conditional attribute definitions.
14150 typed_string_declaration ::=
14151 @b{type} <typed_string_>_simple_name @b{is}
14152 ( string_literal @{, string_literal@} );
14156 A typed string declaration can only appear immediately within a project
14159 All the string literals in a typed string declaration must be distinct.
14165 Variables denote values, and appear as constituents of expressions.
14168 typed_variable_declaration ::=
14169 <typed_variable_>simple_name : <typed_string_>name := string_expression ;
14171 variable_declaration ::=
14172 <variable_>simple_name := expression;
14176 The elaboration of a variable declaration introduces the variable and
14177 assigns to it the value of the expression. The name of the variable is
14178 available after the assignment symbol.
14181 A typed_variable can only be declare once.
14184 a non typed variable can be declared multiple times.
14187 Before the completion of its first declaration, the value of variable
14188 is the null string.
14191 @section Expressions
14194 An expression is a formula that defines a computation or retrieval of a value.
14195 In a project file the value of an expression is either a string or a list
14196 of strings. A string value in an expression is either a literal, the current
14197 value of a variable, an external value, an attribute reference, or a
14198 concatenation operation.
14211 attribute_reference
14217 ( <string_>expression @{ , <string_>expression @} )
14220 @subsection Concatenation
14222 The following concatenation functions are defined:
14224 @smallexample @c ada
14225 function "&" (X : String; Y : String) return String;
14226 function "&" (X : String_List; Y : String) return String_List;
14227 function "&" (X : String_List; Y : String_List) return String_List;
14231 @section Attributes
14234 An attribute declaration defines a property of a project or package. This
14235 property can later be queried by means of an attribute reference.
14236 Attribute values are strings or string lists.
14238 Some attributes are associative arrays. These attributes are mappings whose
14239 domain is a set of strings. These attributes are declared one association
14240 at a time, by specifying a point in the domain and the corresponding image
14241 of the attribute. They may also be declared as a full associative array,
14242 getting the same associations as the corresponding attribute in an imported
14243 or extended project.
14245 Attributes that are not associative arrays are called simple attributes.
14249 attribute_declaration ::=
14250 full_associative_array_declaration |
14251 @b{for} attribute_designator @b{use} expression ;
14253 full_associative_array_declaration ::=
14254 @b{for} <associative_array_attribute_>simple_name @b{use}
14255 <project_>simple_name [ . <package_>simple_Name ] ' <attribute_>simple_name ;
14257 attribute_designator ::=
14258 <simple_attribute_>simple_name |
14259 <associative_array_attribute_>simple_name ( string_literal )
14263 Some attributes are project-specific, and can only appear immediately within
14264 a project declaration. Others are package-specific, and can only appear within
14265 the proper package.
14267 The expression in an attribute definition must be a string or a string_list.
14268 The string literal appearing in the attribute_designator of an associative
14269 array attribute is case-insensitive.
14271 @node Project Attributes
14272 @section Project Attributes
14275 The following attributes apply to a project. All of them are simple
14280 Expression must be a path name. The attribute defines the
14281 directory in which the object files created by the build are to be placed. If
14282 not specified, object files are placed in the project directory.
14285 Expression must be a path name. The attribute defines the
14286 directory in which the executables created by the build are to be placed.
14287 If not specified, executables are placed in the object directory.
14290 Expression must be a list of path names. The attribute
14291 defines the directories in which the source files for the project are to be
14292 found. If not specified, source files are found in the project directory.
14295 Expression must be a list of file names. The attribute
14296 defines the individual files, in the project directory, which are to be used
14297 as sources for the project. File names are path_names that contain no directory
14298 information. If the project has no sources the attribute must be declared
14299 explicitly with an empty list.
14301 @item Source_List_File
14302 Expression must a single path name. The attribute
14303 defines a text file that contains a list of source file names to be used
14304 as sources for the project
14307 Expression must be a path name. The attribute defines the
14308 directory in which a library is to be built. The directory must exist, must
14309 be distinct from the project's object directory, and must be writable.
14312 Expression must be a string that is a legal file name,
14313 without extension. The attribute defines a string that is used to generate
14314 the name of the library to be built by the project.
14317 Argument must be a string value that must be one of the
14318 following @code{"static"}, @code{"dynamic"} or @code{"relocatable"}. This
14319 string is case-insensitive. If this attribute is not specified, the library is
14320 a static library. Otherwise, the library may be dynamic or relocatable. This
14321 distinction is operating-system dependent.
14323 @item Library_Version
14324 Expression must be a string value whose interpretation
14325 is platform dependent. On UNIX, it is used only for dynamic/relocatable
14326 libraries as the internal name of the library (the @code{"soname"}). If the
14327 library file name (built from the @code{Library_Name}) is different from the
14328 @code{Library_Version}, then the library file will be a symbolic link to the
14329 actual file whose name will be @code{Library_Version}.
14331 @item Library_Interface
14332 Expression must be a string list. Each element of the string list
14333 must designate a unit of the project.
14334 If this attribute is present in a Library Project File, then the project
14335 file is a Stand-alone Library_Project_File.
14337 @item Library_Auto_Init
14338 Expression must be a single string "true" or "false", case-insensitive.
14339 If this attribute is present in a Stand-alone Library Project File,
14340 it indicates if initialization is automatic when the dynamic library
14343 @item Library_Options
14344 Expression must be a string list. Indicates additional switches that
14345 are to be used when building a shared library.
14348 Expression must be a single string. Designates an alternative to "gcc"
14349 for building shared libraries.
14351 @item Library_Src_Dir
14352 Expression must be a path name. The attribute defines the
14353 directory in which the sources of the interfaces of a Stand-alone Library will
14354 be copied. The directory must exist, must be distinct from the project's
14355 object directory and source directories, and must be writable.
14358 Expression must be a list of strings that are legal file names.
14359 These file names designate existing compilation units in the source directory
14360 that are legal main subprograms.
14362 When a project file is elaborated, as part of the execution of a gnatmake
14363 command, one or several executables are built and placed in the Exec_Dir.
14364 If the gnatmake command does not include explicit file names, the executables
14365 that are built correspond to the files specified by this attribute.
14367 @item Main_Language
14368 This is a simple attribute. Its value is a string that specifies the
14369 language of the main program.
14372 Expression must be a string list. Each string designates
14373 a programming language that is known to GNAT. The strings are case-insensitive.
14375 @item Locally_Removed_Files
14376 This attribute is legal only in a project file that extends another.
14377 Expression must be a list of strings that are legal file names.
14378 Each file name must designate a source that would normally be inherited
14379 by the current project file. It cannot designate an immediate source that is
14380 not inherited. Each of the source files in the list are not considered to
14381 be sources of the project file: they are not inherited.
14384 @node Attribute References
14385 @section Attribute References
14388 Attribute references are used to retrieve the value of previously defined
14389 attribute for a package or project.
14392 attribute_reference ::=
14393 attribute_prefix ' <simple_attribute_>simple_name [ ( string_literal ) ]
14395 attribute_prefix ::=
14397 <project_simple_name | package_identifier |
14398 <project_>simple_name . package_identifier
14402 If an attribute has not been specified for a given package or project, its
14403 value is the null string or the empty list.
14405 @node External Values
14406 @section External Values
14409 An external value is an expression whose value is obtained from the command
14410 that invoked the processing of the current project file (typically a
14416 @b{external} ( string_literal [, string_literal] )
14420 The first string_literal is the string to be used on the command line or
14421 in the environment to specify the external value. The second string_literal,
14422 if present, is the default to use if there is no specification for this
14423 external value either on the command line or in the environment.
14425 @node Case Construction
14426 @section Case Construction
14429 A case construction supports attribute declarations that depend on the value of
14430 a previously declared variable.
14434 case_construction ::=
14435 @b{case} <typed_variable_>name @b{is}
14440 @b{when} discrete_choice_list =>
14441 @{case_construction | attribute_declaration | empty_declaration@}
14443 discrete_choice_list ::=
14444 string_literal @{| string_literal@} |
14449 All choices in a choice list must be distinct. The choice lists of two
14450 distinct alternatives must be disjoint. Unlike Ada, the choice lists of all
14451 alternatives do not need to include all values of the type. An @code{others}
14452 choice must appear last in the list of alternatives.
14458 A package provides a grouping of variable declarations and attribute
14459 declarations to be used when invoking various GNAT tools. The name of
14460 the package indicates the tool(s) to which it applies.
14464 package_declaration ::=
14465 package_specification | package_renaming
14467 package_specification ::=
14468 @b{package} package_identifier @b{is}
14469 @{simple_declarative_item@}
14470 @b{end} package_identifier ;
14472 package_identifier ::=
14473 @code{Naming} | @code{Builder} | @code{Compiler} | @code{Binder} |
14474 @code{Linker} | @code{Finder} | @code{Cross_Reference} |
14475 @code{gnatls} | @code{IDE} | @code{Pretty_Printer}
14478 @subsection Package Naming
14481 The attributes of a @code{Naming} package specifies the naming conventions
14482 that apply to the source files in a project. When invoking other GNAT tools,
14483 they will use the sources in the source directories that satisfy these
14484 naming conventions.
14486 The following attributes apply to a @code{Naming} package:
14490 This is a simple attribute whose value is a string. Legal values of this
14491 string are @code{"lowercase"}, @code{"uppercase"} or @code{"mixedcase"}.
14492 These strings are themselves case insensitive.
14495 If @code{Casing} is not specified, then the default is @code{"lowercase"}.
14497 @item Dot_Replacement
14498 This is a simple attribute whose string value satisfies the following
14502 @item It must not be empty
14503 @item It cannot start or end with an alphanumeric character
14504 @item It cannot be a single underscore
14505 @item It cannot start with an underscore followed by an alphanumeric
14506 @item It cannot contain a dot @code{'.'} if longer than one character
14510 If @code{Dot_Replacement} is not specified, then the default is @code{"-"}.
14513 This is an associative array attribute, defined on language names,
14514 whose image is a string that must satisfy the following
14518 @item It must not be empty
14519 @item It cannot start with an alphanumeric character
14520 @item It cannot start with an underscore followed by an alphanumeric character
14524 For Ada, the attribute denotes the suffix used in file names that contain
14525 library unit declarations, that is to say units that are package and
14526 subprogram declarations. If @code{Spec_Suffix ("Ada")} is not
14527 specified, then the default is @code{".ads"}.
14529 For C and C++, the attribute denotes the suffix used in file names that
14530 contain prototypes.
14533 This is an associative array attribute defined on language names,
14534 whose image is a string that must satisfy the following
14538 @item It must not be empty
14539 @item It cannot start with an alphanumeric character
14540 @item It cannot start with an underscore followed by an alphanumeric character
14541 @item It cannot be a suffix of @code{Spec_Suffix}
14545 For Ada, the attribute denotes the suffix used in file names that contain
14546 library bodies, that is to say units that are package and subprogram bodies.
14547 If @code{Body_Suffix ("Ada")} is not specified, then the default is
14550 For C and C++, the attribute denotes the suffix used in file names that contain
14553 @item Separate_Suffix
14554 This is a simple attribute whose value satisfies the same conditions as
14555 @code{Body_Suffix}.
14557 This attribute is specific to Ada. It denotes the suffix used in file names
14558 that contain separate bodies. If it is not specified, then it defaults to same
14559 value as @code{Body_Suffix ("Ada")}.
14562 This is an associative array attribute, specific to Ada, defined over
14563 compilation unit names. The image is a string that is the name of the file
14564 that contains that library unit. The file name is case sensitive if the
14565 conventions of the host operating system require it.
14568 This is an associative array attribute, specific to Ada, defined over
14569 compilation unit names. The image is a string that is the name of the file
14570 that contains the library unit body for the named unit. The file name is case
14571 sensitive if the conventions of the host operating system require it.
14573 @item Specification_Exceptions
14574 This is an associative array attribute defined on language names,
14575 whose value is a list of strings.
14577 This attribute is not significant for Ada.
14579 For C and C++, each string in the list denotes the name of a file that
14580 contains prototypes, but whose suffix is not necessarily the
14581 @code{Spec_Suffix} for the language.
14583 @item Implementation_Exceptions
14584 This is an associative array attribute defined on language names,
14585 whose value is a list of strings.
14587 This attribute is not significant for Ada.
14589 For C and C++, each string in the list denotes the name of a file that
14590 contains source code, but whose suffix is not necessarily the
14591 @code{Body_Suffix} for the language.
14594 The following attributes of package @code{Naming} are obsolescent. They are
14595 kept as synonyms of other attributes for compatibility with previous versions
14596 of the Project Manager.
14599 @item Specification_Suffix
14600 This is a synonym of @code{Spec_Suffix}.
14602 @item Implementation_Suffix
14603 This is a synonym of @code{Body_Suffix}.
14605 @item Specification
14606 This is a synonym of @code{Spec}.
14608 @item Implementation
14609 This is a synonym of @code{Body}.
14612 @subsection package Compiler
14615 The attributes of the @code{Compiler} package specify the compilation options
14616 to be used by the underlying compiler.
14619 @item Default_Switches
14620 This is an associative array attribute. Its
14621 domain is a set of language names. Its range is a string list that
14622 specifies the compilation options to be used when compiling a component
14623 written in that language, for which no file-specific switches have been
14627 This is an associative array attribute. Its domain is
14628 a set of file names. Its range is a string list that specifies the
14629 compilation options to be used when compiling the named file. If a file
14630 is not specified in the Switches attribute, it is compiled with the
14631 settings specified by Default_Switches.
14633 @item Local_Configuration_Pragmas.
14634 This is a simple attribute, whose
14635 value is a path name that designates a file containing configuration pragmas
14636 to be used for all invocations of the compiler for immediate sources of the
14640 This is an associative array attribute. Its domain is
14641 a set of main source file names. Its range is a simple string that specifies
14642 the executable file name to be used when linking the specified main source.
14643 If a main source is not specified in the Executable attribute, the executable
14644 file name is deducted from the main source file name.
14647 @subsection package Builder
14650 The attributes of package @code{Builder} specify the compilation, binding, and
14651 linking options to be used when building an executable for a project. The
14652 following attributes apply to package @code{Builder}:
14655 @item Default_Switches
14661 @item Global_Configuration_Pragmas
14662 This is a simple attribute, whose
14663 value is a path name that designates a file that contains configuration pragmas
14664 to be used in every build of an executable. If both local and global
14665 configuration pragmas are specified, a compilation makes use of both sets.
14668 This is an associative array attribute, defined over
14669 compilation unit names. The image is a string that is the name of the
14670 executable file corresponding to the main source file index.
14671 This attribute has no effect if its value is the empty string.
14673 @item Executable_Suffix
14674 This is a simple attribute whose value is a suffix to be added to
14675 the executables that don't have an attribute Executable specified.
14678 @subsection package Gnatls
14681 The attributes of package @code{Gnatls} specify the tool options to be used
14682 when invoking the library browser @command{gnatls}.
14683 The following attributes apply to package @code{Gnatls}:
14690 @subsection package Binder
14693 The attributes of package @code{Binder} specify the options to be used
14694 when invoking the binder in the construction of an executable.
14695 The following attributes apply to package @code{Binder}:
14698 @item Default_Switches
14704 @subsection package Linker
14707 The attributes of package @code{Linker} specify the options to be used when
14708 invoking the linker in the construction of an executable.
14709 The following attributes apply to package @code{Linker}:
14712 @item Default_Switches
14718 @subsection package Cross_Reference
14721 The attributes of package @code{Cross_Reference} specify the tool options
14723 when invoking the library tool @command{gnatxref}.
14724 The following attributes apply to package @code{Cross_Reference}:
14727 @item Default_Switches
14733 @subsection package Finder
14736 The attributes of package @code{Finder} specify the tool options to be used
14737 when invoking the search tool @command{gnatfind}.
14738 The following attributes apply to package @code{Finder}:
14741 @item Default_Switches
14747 @subsection package Pretty_Printer
14750 The attributes of package @code{Pretty_Printer}
14751 specify the tool options to be used
14752 when invoking the formatting tool @command{gnatpp}.
14753 The following attributes apply to package @code{Pretty_Printer}:
14756 @item Default_switches
14762 @subsection package IDE
14765 The attributes of package @code{IDE} specify the options to be used when using
14766 an Integrated Development Environment such as @command{GPS}.
14770 This is a simple attribute. Its value is a string that designates the remote
14771 host in a cross-compilation environment, to be used for remote compilation and
14772 debugging. This field should not be specified when running on the local
14776 This is a simple attribute. Its value is a string that specifies the
14777 name of IP address of the embedded target in a cross-compilation environment,
14778 on which the program should execute.
14780 @item Communication_Protocol
14781 This is a simple string attribute. Its value is the name of the protocol
14782 to use to communicate with the target in a cross-compilation environment,
14783 e.g. @code{"wtx"} or @code{"vxworks"}.
14785 @item Compiler_Command
14786 This is an associative array attribute, whose domain is a language name. Its
14787 value is string that denotes the command to be used to invoke the compiler.
14788 The value of @code{Compiler_Command ("Ada")} is expected to be compatible with
14789 gnatmake, in particular in the handling of switches.
14791 @item Debugger_Command
14792 This is simple attribute, Its value is a string that specifies the name of
14793 the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4.
14795 @item Default_Switches
14796 This is an associative array attribute. Its indexes are the name of the
14797 external tools that the GNAT Programming System (GPS) is supporting. Its
14798 value is a list of switches to use when invoking that tool.
14801 This is a simple attribute. Its value is a string that specifies the name
14802 of the @command{gnatls} utility to be used to retrieve information about the
14803 predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}.
14806 This is a simple attribute. Its value is a string used to specify the
14807 Version Control System (VCS) to be used for this project, e.g CVS, RCS
14808 ClearCase or Perforce.
14810 @item VCS_File_Check
14811 This is a simple attribute. Its value is a string that specifies the
14812 command used by the VCS to check the validity of a file, either
14813 when the user explicitly asks for a check, or as a sanity check before
14814 doing the check-in.
14816 @item VCS_Log_Check
14817 This is a simple attribute. Its value is a string that specifies
14818 the command used by the VCS to check the validity of a log file.
14822 @node Package Renamings
14823 @section Package Renamings
14826 A package can be defined by a renaming declaration. The new package renames
14827 a package declared in a different project file, and has the same attributes
14828 as the package it renames.
14831 package_renaming ::==
14832 @b{package} package_identifier @b{renames}
14833 <project_>simple_name.package_identifier ;
14837 The package_identifier of the renamed package must be the same as the
14838 package_identifier. The project whose name is the prefix of the renamed
14839 package must contain a package declaration with this name. This project
14840 must appear in the context_clause of the enclosing project declaration,
14841 or be the parent project of the enclosing child project.
14847 A project file specifies a set of rules for constructing a software system.
14848 A project file can be self-contained, or depend on other project files.
14849 Dependencies are expressed through a context clause that names other projects.
14855 context_clause project_declaration
14857 project_declaration ::=
14858 simple_project_declaration | project_extension
14860 simple_project_declaration ::=
14861 @b{project} <project_>simple_name @b{is}
14862 @{declarative_item@}
14863 @b{end} <project_>simple_name;
14869 [@b{limited}] @b{with} path_name @{ , path_name @} ;
14876 A path name denotes a project file. A path name can be absolute or relative.
14877 An absolute path name includes a sequence of directories, in the syntax of
14878 the host operating system, that identifies uniquely the project file in the
14879 file system. A relative path name identifies the project file, relative
14880 to the directory that contains the current project, or relative to a
14881 directory listed in the environment variable ADA_PROJECT_PATH.
14882 Path names are case sensitive if file names in the host operating system
14883 are case sensitive.
14885 The syntax of the environment variable ADA_PROJECT_PATH is a list of
14886 directory names separated by colons (semicolons on Windows).
14888 A given project name can appear only once in a context_clause.
14890 It is illegal for a project imported by a context clause to refer, directly
14891 or indirectly, to the project in which this context clause appears (the
14892 dependency graph cannot contain cycles), except when one of the with_clause
14893 in the cycle is a @code{limited with}.
14895 @node Project Extensions
14896 @section Project Extensions
14899 A project extension introduces a new project, which inherits the declarations
14900 of another project.
14904 project_extension ::=
14905 @b{project} <project_>simple_name @b{extends} path_name @b{is}
14906 @{declarative_item@}
14907 @b{end} <project_>simple_name;
14911 The project extension declares a child project. The child project inherits
14912 all the declarations and all the files of the parent project, These inherited
14913 declaration can be overridden in the child project, by means of suitable
14916 @node Project File Elaboration
14917 @section Project File Elaboration
14920 A project file is processed as part of the invocation of a gnat tool that
14921 uses the project option. Elaboration of the process file consists in the
14922 sequential elaboration of all its declarations. The computed values of
14923 attributes and variables in the project are then used to establish the
14924 environment in which the gnat tool will execute.
14926 @node Obsolescent Features
14927 @chapter Obsolescent Features
14930 This chapter describes features that are provided by GNAT, but are
14931 considered obsolescent since there are preferred ways of achieving
14932 the same effect. These features are provided solely for historical
14933 compatibility purposes.
14936 * pragma No_Run_Time::
14937 * pragma Ravenscar::
14938 * pragma Restricted_Run_Time::
14941 @node pragma No_Run_Time
14942 @section pragma No_Run_Time
14944 The pragma @code{No_Run_Time} is used to achieve an affect similar
14945 to the use of the "Zero Foot Print" configurable run time, but without
14946 requiring a specially configured run time. The result of using this
14947 pragma, which must be used for all units in a partition, is to restrict
14948 the use of any language features requiring run-time support code. The
14949 preferred usage is to use an appropriately configured run-time that
14950 includes just those features that are to be made accessible.
14952 @node pragma Ravenscar
14953 @section pragma Ravenscar
14955 The pragma @code{Ravenscar} has exactly the same effect as pragma
14956 @code{Profile (Ravenscar)}. The latter usage is preferred since it
14957 is part of the new Ada 2005 standard.
14959 @node pragma Restricted_Run_Time
14960 @section pragma Restricted_Run_Time
14962 The pragma @code{Restricted_Run_Time} has exactly the same effect as
14963 pragma @code{Profile (Restricted)}. The latter usage is
14964 preferred since the Ada 2005 pragma @code{Profile} is intended for
14965 this kind of implementation dependent addition.
14968 @c GNU Free Documentation License
14970 @node Index,,GNU Free Documentation License, Top
OSDN Git Service
