1 \input texinfo @c -*-texinfo-*-
5 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
7 @c GNAT DOCUMENTATION o
13 @c Copyright (C) 1995-2002 Free Software Foundation o
16 @c GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o
18 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
20 @setfilename gnat_rm.info
21 @settitle GNAT Reference Manual
22 @setchapternewpage odd
25 @dircategory GNU Ada tools
27 * GNAT Reference Manual: (gnat_rm). Reference Manual for GNU Ada tools.
32 @title GNAT Reference Manual
33 @subtitle GNAT, The GNU Ada 95 Compiler
38 @subtitle Version 3.16w
40 @author Ada Core Technologies, Inc.
43 @vskip 0pt plus 1filll
46 Copyright @copyright{} 1995-2001, Free Software Foundation
48 Permission is granted to copy, distribute and/or modify this document
49 under the terms of the GNU Free Documentation License, Version 1.1
50 or any later version published by the Free Software Foundation;
51 with the Invariant Sections being ``GNU Free Documentation License'', with the
52 Front-Cover Texts being ``GNAT Reference Manual'', and with no Back-Cover Texts.
53 A copy of the license is included in the section entitled ``GNU
54 Free Documentation License''.
59 @node Top, About This Guide, (dir), (dir)
60 @top GNAT Reference Manual
65 GNAT, The GNU Ada 95 Compiler
74 Ada Core Technologies, Inc.
77 Copyright @copyright{} 1995-2001, Free Software Foundation
79 Permission is granted to copy, distribute and/or modify this document
80 under the terms of the GNU Free Documentation License, Version 1.1
81 or any later version published by the Free Software Foundation;
82 with the Invariant Sections being ``GNU Free Documentation License'', with the
83 Front-Cover Texts being ``GNAT Reference Manual'', and with no Back-Cover Texts.
84 A copy of the license is included in the section entitled ``GNU
85 Free Documentation License''.
90 * Implementation Defined Pragmas::
91 * Implementation Defined Attributes::
92 * Implementation Advice::
93 * Implementation Defined Characteristics::
94 * Intrinsic Subprograms::
95 * Representation Clauses and Pragmas::
96 * Standard Library Routines::
97 * The Implementation of Standard I/O::
99 * Interfacing to Other Languages::
100 * Machine Code Insertions::
101 * GNAT Implementation of Tasking::
102 * Code generation for array aggregates::
103 * Specialized Needs Annexes::
104 * Compatibility Guide::
105 * GNU Free Documentation License::
108 --- The Detailed Node Listing ---
112 * What This Reference Manual Contains::
113 * Related Information::
115 The Implementation of Standard I/O
117 * Standard I/O Packages::
126 * Operations on C Streams::
127 * Interfacing to C Streams::
131 * Ada.Characters.Latin_9 (a-chlat9.ads)::
132 * Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
133 * Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
134 * Ada.Command_Line.Remove (a-colire.ads)::
135 * Ada.Direct_IO.C_Streams (a-diocst.ads)::
136 * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
137 * Ada.Sequential_IO.C_Streams (a-siocst.ads)::
138 * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
139 * Ada.Strings.Unbounded.Text_IO (a-suteio.ads)::
140 * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
141 * Ada.Text_IO.C_Streams (a-tiocst.ads)::
142 * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
143 * GNAT.AWK (g-awk.ads)::
144 * GNAT.Bubble_Sort_A (g-busora.ads)::
145 * GNAT.Bubble_Sort_G (g-busorg.ads)::
146 * GNAT.Calendar (g-calend.ads)::
147 * GNAT.Calendar.Time_IO (g-catiio.ads)::
148 * GNAT.Case_Util (g-casuti.ads)::
149 * GNAT.CGI (g-cgi.ads)::
150 * GNAT.CGI.Cookie (g-cgicoo.ads)::
151 * GNAT.CGI.Debug (g-cgideb.ads)::
152 * GNAT.Command_Line (g-comlin.ads)::
153 * GNAT.CRC32 (g-crc32.ads)::
154 * GNAT.Current_Exception (g-curexc.ads)::
155 * GNAT.Debug_Pools (g-debpoo.ads)::
156 * GNAT.Debug_Utilities (g-debuti.ads)::
157 * GNAT.Directory_Operations (g-dirope.ads)::
158 * GNAT.Dynamic_Tables (g-dyntab.ads)::
159 * GNAT.Exception_Traces (g-exctra.ads)::
160 * GNAT.Expect (g-expect.ads)::
161 * GNAT.Float_Control (g-flocon.ads)::
162 * GNAT.Heap_Sort_A (g-hesora.ads)::
163 * GNAT.Heap_Sort_G (g-hesorg.ads)::
164 * GNAT.HTable (g-htable.ads)::
165 * GNAT.IO (g-io.ads)::
166 * GNAT.IO_Aux (g-io_aux.ads)::
167 * GNAT.Lock_Files (g-locfil.ads)::
168 * GNAT.MD5 (g-md5.ads)::
169 * GNAT.Most_Recent_Exception (g-moreex.ads)::
170 * GNAT.OS_Lib (g-os_lib.ads)::
171 * GNAT.Regexp (g-regexp.ads)::
172 * GNAT.Registry (g-regist.ads)::
173 * GNAT.Regpat (g-regpat.ads)::
174 * GNAT.Sockets (g-socket.ads)::
175 * GNAT.Source_Info (g-souinf.ads)::
176 * GNAT.Spell_Checker (g-speche.ads)::
177 * GNAT.Spitbol.Patterns (g-spipat.ads)::
178 * GNAT.Spitbol (g-spitbo.ads)::
179 * GNAT.Spitbol.Table_Boolean (g-sptabo.ads)::
180 * GNAT.Spitbol.Table_Integer (g-sptain.ads)::
181 * GNAT.Spitbol.Table_VString (g-sptavs.ads)::
182 * GNAT.Table (g-table.ads)::
183 * GNAT.Task_Lock (g-tasloc.ads)::
184 * GNAT.Threads (g-thread.ads)::
185 * GNAT.Traceback (g-traceb.ads)::
186 * GNAT.Traceback.Symbolic (g-trasym.ads)::
187 * Interfaces.C.Extensions (i-cexten.ads)::
188 * Interfaces.C.Streams (i-cstrea.ads)::
189 * Interfaces.CPP (i-cpp.ads)::
190 * Interfaces.Os2lib (i-os2lib.ads)::
191 * Interfaces.Os2lib.Errors (i-os2err.ads)::
192 * Interfaces.Os2lib.Synchronization (i-os2syn.ads)::
193 * Interfaces.Os2lib.Threads (i-os2thr.ads)::
194 * Interfaces.Packed_Decimal (i-pacdec.ads)::
195 * Interfaces.VxWorks (i-vxwork.ads)::
196 * Interfaces.VxWorks.IO (i-vxwoio.ads)::
197 * System.Address_Image (s-addima.ads)::
198 * System.Assertions (s-assert.ads)::
199 * System.Partition_Interface (s-parint.ads)::
200 * System.Task_Info (s-tasinf.ads)::
201 * System.Wch_Cnv (s-wchcnv.ads)::
202 * System.Wch_Con (s-wchcon.ads)::
206 * Text_IO Stream Pointer Positioning::
207 * Text_IO Reading and Writing Non-Regular Files::
209 * Treating Text_IO Files as Streams::
210 * Text_IO Extensions::
211 * Text_IO Facilities for Unbounded Strings::
215 * Wide_Text_IO Stream Pointer Positioning::
216 * Wide_Text_IO Reading and Writing Non-Regular Files::
218 Interfacing to Other Languages
221 * Interfacing to C++::
222 * Interfacing to COBOL::
223 * Interfacing to Fortran::
224 * Interfacing to non-GNAT Ada code::
226 GNAT Implementation of Tasking
228 * Mapping Ada Tasks onto the Underlying Kernel Threads::
229 * Ensuring Compliance with the Real-Time Annex::
234 @node About This Guide
235 @unnumbered About This Guide
238 This manual contains useful information in writing programs using the
239 GNAT compiler. It includes information on implementation dependent
240 characteristics of GNAT, including all the information required by Annex
243 Ada 95 is designed to be highly portable,and guarantees that, for most
244 programs, Ada 95 compilers behave in exactly the same manner on
245 different machines. However, since Ada 95 is designed to be used in a
246 wide variety of applications, it also contains a number of system
247 dependent features to Functbe used in interfacing to the external world.
249 @c Maybe put the following in platform-specific section
252 This reference manual discusses how these features are implemented for
253 use in ProDev Ada running on the IRIX 5.3 or greater operating systems.
256 @cindex Implementation-dependent features
258 Note: Any program that makes use of implementation-dependent features
259 may be non-portable. You should follow good programming practice and
260 isolate and clearly document any sections of your program that make use
261 of these features in a non-portable manner.
264 * What This Reference Manual Contains::
266 * Related Information::
269 @node What This Reference Manual Contains
270 @unnumberedsec What This Reference Manual Contains
272 This reference manual contains the following chapters:
276 @ref{Implementation Defined Pragmas} lists GNAT implementation-dependent
277 pragmas, which can be used to extend and enhance the functionality of the
281 @ref{Implementation Defined Attributes} lists GNAT
282 implementation-dependent attributes which can be used to extend and
283 enhance the functionality of the compiler.
286 @ref{Implementation Advice} provides information on generally
287 desirable behavior which are not requirements that all compilers must
288 follow since it cannot be provided on all systems, or which may be
289 undesirable on some systems.
292 @ref{Implementation Defined Characteristics} provides a guide to
293 minimizing implementation dependent features.
296 @ref{Intrinsic Subprograms} describes the intrinsic subprograms
297 implemented by GNAT, and how they can be imported into user
298 application programs.
301 @ref{Representation Clauses and Pragmas} describes in detail the
302 way that GNAT represents data, and in particular the exact set
303 of representation clauses and pragmas that is accepted.
306 @ref{Standard Library Routines} provides a listing of packages and a
307 brief description of the functionality that is provided by Ada's
308 extensive set of standard library routines as implemented by GNAT@.
311 @ref{The Implementation of Standard I/O} details how the GNAT
312 implementation of the input-output facilities.
315 @ref{Interfacing to Other Languages} describes how programs
316 written in Ada using GNAT can be interfaced to other programming
320 @ref{Specialized Needs Annexes} describes the GNAT implementation of all
321 of the special needs annexes.
324 @ref{Compatibility Guide} includes sections on compatibility of GNAT with
325 other Ada 83 and Ada 95 compilation systems, to assist in porting code
326 from other environments.
329 @cindex Ada 95 ISO/ANSI Standard
330 This reference manual assumes that you are familiar with Ada 95
331 language, as described in the International Standard
332 ANSI/ISO/IEC-8652:1995, Jan 1995.
335 @unnumberedsec Conventions
336 @cindex Conventions, typographical
337 @cindex Typographical conventions
340 Following are examples of the typographical and graphic conventions used
345 @code{Functions}, @code{utility program names}, @code{standard names},
352 @file{File Names}, @samp{button names}, and @samp{field names}.
361 [optional information or parameters]
364 Examples are described by text
366 and then shown this way.
371 Commands that are entered by the user are preceded in this manual by the
372 characters @samp{$ } (dollar sign followed by space). If your system uses this
373 sequence as a prompt, then the commands will appear exactly as you see them
374 in the manual. If your system uses some other prompt, then the command will
375 appear with the @samp{$} replaced by whatever prompt character you are using.
377 @node Related Information
378 @unnumberedsec Related Information
379 See the following documents for further information on GNAT:
383 @cite{GNAT User's Guide}, which provides information on how to use
384 the GNAT compiler system.
387 @cite{Ada 95 Reference Manual}, which contains all reference
388 material for the Ada 95 programming language.
391 @cite{Ada 95 Annotated Reference Manual}, which is an annotated version
392 of the standard reference manual cited above. The annotations describe
393 detailed aspects of the design decision, and in particular contain useful
394 sections on Ada 83 compatibility.
397 @cite{DEC Ada, Technical Overview and Comparison on DIGITAL Platforms},
398 which contains specific information on compatibility between GNAT and
402 @cite{DEC Ada, Language Reference Manual, part number AA-PYZAB-TK} which
403 describes in detail the pragmas and attributes provided by the DEC Ada 83
408 @node Implementation Defined Pragmas
409 @chapter Implementation Defined Pragmas
412 Ada 95 defines a set of pragmas that can be used to supply additional
413 information to the compiler. These language defined pragmas are
414 implemented in GNAT and work as described in the Ada 95 Reference
417 In addition, Ada 95 allows implementations to define additional pragmas
418 whose meaning is defined by the implementation. GNAT provides a number
419 of these implementation-dependent pragmas which can be used to extend
420 and enhance the functionality of the compiler. This section of the GNAT
421 Reference Manual describes these additional pragmas.
423 Note that any program using these pragmas may not be portable to other
424 compilers (although GNAT implements this set of pragmas on all
425 platforms). Therefore if portability to other compilers is an important
426 consideration, the use of these pragmas should be minimized.
431 @cindex Deferring aborts
432 @item pragma Abort_Defer
441 This pragma must appear at the start of the statement sequence of a
442 handled sequence of statements (right after the @code{begin}). It has
443 the effect of deferring aborts for the sequence of statements (but not
444 for the declarations or handlers, if any, associated with this statement
457 A configuration pragma that establishes Ada 83 mode for the unit to
458 which it applies, regardless of the mode set by the command line
459 switches. In Ada 83 mode, GNAT attempts to be as compatible with
460 the syntax and semantics of Ada 83, as defined in the original Ada
461 83 Reference Manual as possible. In particular, the new Ada 95
462 keywords are not recognized, optional package bodies are allowed,
463 and generics may name types with unknown discriminants without using
464 the @code{(<>)} notation. In addition, some but not all of the additional
465 restrictions of Ada 83 are enforced.
467 Ada 83 mode is intended for two purposes. Firstly, it allows existing
468 legacy Ada 83 code to be compiled and adapted to GNAT with less effort.
469 Secondly, it aids in keeping code backwards compatible with Ada 83.
470 However, there is no guarantee that code that is processed correctly
471 by GNAT in Ada 83 mode will in fact compile and execute with an Ada
472 83 compiler, since GNAT does not enforce all the additional checks
485 A configuration pragma that establishes Ada 95 mode for the unit to which
486 it applies, regardless of the mode set by the command line switches.
487 This mode is set automatically for the @code{Ada} and @code{System}
488 packages and their children, so you need not specify it in these
489 contexts. This pragma is useful when writing a reusable component that
490 itself uses Ada 95 features, but which is intended to be usable from
491 either Ada 83 or Ada 95 programs.
494 @item pragma Annotate
499 pragma Annotate (IDENTIFIER @{, ARG@});
501 ARG ::= NAME | EXPRESSION
505 This pragma is used to annotate programs. @var{identifier} identifies
506 the type of annotation. GNAT verifies this is an identifier, but does
507 not otherwise analyze it. The @var{arg} argument
508 can be either a string literal or an
509 expression. String literals are assumed to be of type
510 @code{Standard.String}. Names of entities are simply analyzed as entity
511 names. All other expressions are analyzed as expressions, and must be
514 The analyzed pragma is retained in the tree, but not otherwise processed
515 by any part of the GNAT compiler. This pragma is intended for use by
516 external tools, including ASIS@.
526 [, static_string_EXPRESSION])
530 The effect of this pragma depends on whether the corresponding command
531 line switch is set to activate assertions. The pragma expands into code
532 equivalent to the following:
535 if assertions-enabled then
536 if not boolean_EXPRESSION then
537 System.Assertions.Raise_Assert_Failure
544 The string argument, if given, is the message that will be associated
545 with the exception occurrence if the exception is raised. If no second
546 argument is given, the default message is @samp{@var{file}:@var{nnn}},
547 where @var{file} is the name of the source file containing the assert,
548 and @var{nnn} is the line number of the assert. A pragma is not a
549 statement, so if a statement sequence contains nothing but a pragma
550 assert, then a null statement is required in addition, as in:
555 pragma Assert (K > 3, "Bad value for K");
561 Note that, as with the @code{if} statement to which it is equivalent, the
562 type of the expression is either @code{Standard.Boolean}, or any type derived
563 from this standard type.
565 If assertions are disabled (switch @code{-gnata} not used), then there
566 is no effect (and in particular, any side effects from the expression
567 are suppressed). More precisely it is not quite true that the pragma
568 has no effect, since the expression is analyzed, and may cause types
569 to be frozen if they are mentioned here for the first time.
571 If assertions are enabled, then the given expression is tested, and if
572 it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called
573 which results in the raising of @code{Assert_Failure} with the given message.
575 If the boolean expression has side effects, these side effects will turn
576 on and off with the setting of the assertions mode, resulting in
577 assertions that have an effect on the program. You should generally
578 avoid side effects in the expression arguments of this pragma. However,
579 the expressions are analyzed for semantic correctness whether or not
580 assertions are enabled, so turning assertions on and off cannot affect
581 the legality of a program.
585 @item pragma Ast_Entry
590 pragma AST_Entry (entry_IDENTIFIER);
594 This pragma is implemented only in the OpenVMS implementation of GNAT@. The
595 argument is the simple name of a single entry; at most one @code{AST_Entry}
596 pragma is allowed for any given entry. This pragma must be used in
597 conjunction with the @code{AST_Entry} attribute, and is only allowed after
598 the entry declaration and in the same task type specification or single task
599 as the entry to which it applies. This pragma specifies that the given entry
600 may be used to handle an OpenVMS asynchronous system trap (@code{AST})
601 resulting from an OpenVMS system service call. The pragma does not affect
602 normal use of the entry. For further details on this pragma, see the
603 DEC Ada Language Reference Manual, section 9.12a.
605 @cindex Passing by copy
606 @findex C_Pass_By_Copy
607 @item pragma C_Pass_By_Copy
612 pragma C_Pass_By_Copy
613 ([Max_Size =>] static_integer_EXPRESSION);
617 Normally the default mechanism for passing C convention records to C
618 convention subprograms is to pass them by reference, as suggested by RM
619 B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change
620 this default, by requiring that record formal parameters be passed by
621 copy if all of the following conditions are met:
625 The size of the record type does not exceed@*@var{static_integer_expression}.
627 The record type has @code{Convention C}.
629 The formal parameter has this record type, and the subprogram has a
630 foreign (non-Ada) convention.
634 If these conditions are met the argument is passed by copy, i.e.@: in a
635 manner consistent with what C expects if the corresponding formal in the
636 C prototype is a struct (rather than a pointer to a struct).
638 You can also pass records by copy by specifying the convention
639 @code{C_Pass_By_Copy} for the record type, or by using the extended
640 @code{Import} and @code{Export} pragmas, which allow specification of
641 passing mechanisms on a parameter by parameter basis.
649 pragma Comment (static_string_EXPRESSION);
653 This is almost identical in effect to pragma @code{Ident}. It allows the
654 placement of a comment into the object file and hence into the
655 executable file if the operating system permits such usage. The
656 difference is that @code{Comment}, unlike @code{Ident}, has no limit on the
657 length of the string argument, and no limitations on placement
658 of the pragma (it can be placed anywhere in the main source unit).
660 @findex Common_Object
661 @item pragma Common_Object
666 pragma Common_Object (
667 [Internal =>] LOCAL_NAME,
668 [, [External =>] EXTERNAL_SYMBOL]
669 [, [Size =>] EXTERNAL_SYMBOL] )
673 | static_string_EXPRESSION
677 This pragma enables the shared use of variables stored in overlaid
678 linker areas corresponding to the use of @code{COMMON}
679 in Fortran. The single
680 object @var{local_name} is assigned to the area designated by
681 the @var{External} argument.
682 You may define a record to correspond to a series
683 of fields. The @var{size} argument
684 is syntax checked in GNAT, but otherwise ignored.
686 @code{Common_Object} is not supported on all platforms. If no
687 support is available, then the code generator will issue a message
688 indicating that the necessary attribute for implementation of this
689 pragma is not available.
691 @findex Complex_Representation
692 @item pragma Complex_Representation
697 pragma Complex_Representation
698 ([Entity =>] LOCAL_NAME);
702 The @var{Entity} argument must be the name of a record type which has
703 two fields of the same floating-point type. The effect of this pragma is
704 to force gcc to use the special internal complex representation form for
705 this record, which may be more efficient. Note that this may result in
706 the code for this type not conforming to standard ABI (application
707 binary interface) requirements for the handling of record types. For
708 example, in some environments, there is a requirement for passing
709 records by pointer, and the use of this pragma may result in passing
710 this type in floating-point registers.
712 @cindex Alignments of components
713 @findex Component_Alignment
714 @item pragma Component_Alignment
719 pragma Component_Alignment (
720 [Form =>] ALIGNMENT_CHOICE
721 [, [Name =>] type_LOCAL_NAME]);
731 Specifies the alignment of components in array or record types.
732 The meaning of the @var{Form} argument is as follows:
735 @findex Component_Size
737 Aligns scalar components and subcomponents of the array or record type
738 on boundaries appropriate to their inherent size (naturally
739 aligned). For example, 1-byte components are aligned on byte boundaries,
740 2-byte integer components are aligned on 2-byte boundaries, 4-byte
741 integer components are aligned on 4-byte boundaries and so on. These
742 alignment rules correspond to the normal rules for C compilers on all
743 machines except the VAX@.
745 @findex Component_Size_4
746 @item Component_Size_4
747 Naturally aligns components with a size of four or fewer
748 bytes. Components that are larger than 4 bytes are placed on the next
753 Specifies that array or record components are byte aligned, i.e.@:
754 aligned on boundaries determined by the value of the constant
755 @code{System.Storage_Unit}.
759 Specifies that array or record components are aligned on default
760 boundaries, appropriate to the underlying hardware or operating system or
761 both. For OpenVMS VAX systems, the @code{Default} choice is the same as
762 the @code{Storage_Unit} choice (byte alignment). For all other systems,
763 the @code{Default} choice is the same as @code{Component_Size} (natural
767 If the @code{Name} parameter is present, @var{type_local_name} must
768 refer to a local record or array type, and the specified alignment
769 choice applies to the specified type. The use of
770 @code{Component_Alignment} together with a pragma @code{Pack} causes the
771 @code{Component_Alignment} pragma to be ignored. The use of
772 @code{Component_Alignment} together with a record representation clause
773 is only effective for fields not specified by the representation clause.
775 If the @code{Name} parameter is absent, the pragma can be used as either
776 a configuration pragma, in which case it applies to one or more units in
777 accordance with the normal rules for configuration pragmas, or it can be
778 used within a declarative part, in which case it applies to types that
779 are declared within this declarative part, or within any nested scope
780 within this declarative part. In either case it specifies the alignment
781 to be applied to any record or array type which has otherwise standard
784 If the alignment for a record or array type is not specified (using
785 pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep
786 clause), the GNAT uses the default alignment as described previously.
788 @findex Convention_Identifier
789 @cindex Conventions, synonyms
790 @item pragma Convention_Identifier
795 pragma Convention_Identifier (
796 [Name =>] IDENTIFIER,
797 [Convention =>] convention_IDENTIFIER);
801 This pragma provides a mechanism for supplying synonyms for existing
802 convention identifiers. The @code{Name} identifier can subsequently
803 be used as a synonym for the given convention in other pragmas (including
804 for example pragma @code{Import} or another @code{Convention_Identifier}
805 pragma). As an example of the use of this, suppose you had legacy code
806 which used Fortran77 as the identifier for Fortran. Then the pragma:
809 pragma Convention_Indentifier (Fortran77, Fortran);
813 would allow the use of the convention identifier @code{Fortran77} in
814 subsequent code, avoiding the need to modify the sources. As another
815 example, you could use this to parametrize convention requirements
816 according to systems. Suppose you needed to use @code{Stdcall} on
817 windows systems, and @code{C} on some other system, then you could
818 define a convention identifier @code{Library} and use a single
819 @code{Convention_Identifier} pragma to specify which convention
820 would be used system-wide.
823 @cindex Interfacing with C++
824 @item pragma CPP_Class
829 pragma CPP_Class ([Entity =>] LOCAL_NAME);
833 The argument denotes an entity in the current declarative region
834 that is declared as a tagged or untagged record type. It indicates that
835 the type corresponds to an externally declared C++ class type, and is to
836 be laid out the same way that C++ would lay out the type.
838 If (and only if) the type is tagged, at least one component in the
839 record must be of type @code{Interfaces.CPP.Vtable_Ptr}, corresponding
840 to the C++ Vtable (or Vtables in the case of multiple inheritance) used
843 Types for which @code{CPP_Class} is specified do not have assignment or
844 equality operators defined (such operations can be imported or declared
845 as subprograms as required). Initialization is allowed only by
846 constructor functions (see pragma @code{CPP_Constructor}).
848 Pragma @code{CPP_Class} is intended primarily for automatic generation
849 using an automatic binding generator tool.
850 See @ref{Interfacing to C++} for related information.
852 @cindex Interfacing with C++
853 @findex CPP_Constructor
854 @item pragma CPP_Constructor
859 pragma CPP_Constructor ([Entity =>] LOCAL_NAME);
863 This pragma identifies an imported function (imported in the usual way
864 with pragma @code{Import}) as corresponding to a C++
865 constructor. The argument is a name that must have been
866 previously mentioned in a pragma @code{Import}
867 with @code{Convention} = @code{CPP}, and must be of one of the following
872 @code{function @var{Fname} return @var{T}'Class}
875 @code{function @var{Fname} (@dots{}) return @var{T}'Class}
879 where @var{T} is a tagged type to which the pragma @code{CPP_Class} applies.
881 The first form is the default constructor, used when an object of type
882 @var{T} is created on the Ada side with no explicit constructor. Other
883 constructors (including the copy constructor, which is simply a special
884 case of the second form in which the one and only argument is of type
885 @var{T}), can only appear in two contexts:
889 On the right side of an initialization of an object of type @var{T}.
891 In an extension aggregate for an object of a type derived from @var{T}.
894 Although the constructor is described as a function that returns a value
895 on the Ada side, it is typically a procedure with an extra implicit
896 argument (the object being initialized) at the implementation
897 level. GNAT issues the appropriate call, whatever it is, to get the
898 object properly initialized.
900 In the case of derived objects, you may use one of two possible forms
901 for declaring and creating an object:
904 @item @code{New_Object : Derived_T}
905 @item @code{New_Object : Derived_T := (@var{constructor-function-call with} @dots{})}
908 In the first case the default constructor is called and extension fields
909 if any are initialized according to the default initialization
910 expressions in the Ada declaration. In the second case, the given
911 constructor is called and the extension aggregate indicates the explicit
912 values of the extension fields.
914 If no constructors are imported, it is impossible to create any objects
915 on the Ada side. If no default constructor is imported, only the
916 initialization forms using an explicit call to a constructor are
919 Pragma @code{CPP_Constructor} is intended primarily for automatic generation
920 using an automatic binding generator tool.
921 See @ref{Interfacing to C++} for more related information.
923 @cindex Interfacing to C++
925 @item pragma CPP_Virtual
932 [, [Vtable_Ptr =>] vtable_ENTITY,]
933 [, [Position =>] static_integer_EXPRESSION])
936 This pragma serves the same function as pragma @code{Import} in that
937 case of a virtual function imported from C++. The @var{Entity} argument
939 primitive subprogram of a tagged type to which pragma @code{CPP_Class}
940 applies. The @var{Vtable_Ptr} argument specifies
941 the Vtable_Ptr component which contains the
942 entry for this virtual function. The @var{Position} argument
943 is the sequential number
944 counting virtual functions for this Vtable starting at 1.
946 The @code{Vtable_Ptr} and @code{Position} arguments may be omitted if
947 there is one Vtable_Ptr present (single inheritance case) and all
948 virtual functions are imported. In that case the compiler can deduce both
951 No @code{External_Name} or @code{Link_Name} arguments are required for a
952 virtual function, since it is always accessed indirectly via the
953 appropriate Vtable entry.
955 Pragma @code{CPP_Virtual} is intended primarily for automatic generation
956 using an automatic binding generator tool.
957 See @ref{Interfacing to C++} for related information.
959 @cindex Interfacing with C++
961 @item pragma CPP_Vtable
968 [Vtable_Ptr =>] vtable_ENTITY,
969 [Entry_Count =>] static_integer_EXPRESSION);
973 Given a record to which the pragma @code{CPP_Class} applies,
974 this pragma can be specified for each component of type
975 @code{CPP.Interfaces.Vtable_Ptr}.
976 @var{Entity} is the tagged type, @var{Vtable_Ptr}
977 is the record field of type @code{Vtable_Ptr}, and @var{Entry_Count} is
978 the number of virtual functions on the C++ side. Not all of these
979 functions need to be imported on the Ada side.
981 You may omit the @code{CPP_Vtable} pragma if there is only one
982 @code{Vtable_Ptr} component in the record and all virtual functions are
983 imported on the Ada side (the default value for the entry count in this
984 case is simply the total number of virtual functions).
986 Pragma @code{CPP_Vtable} is intended primarily for automatic generation
987 using an automatic binding generator tool.
988 See @ref{Interfacing to C++} for related information.
996 pragma Debug (PROCEDURE_CALL_WITHOUT_SEMICOLON);
998 PROCEDURE_CALL_WITHOUT_SEMICOLON ::=
1000 | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART
1004 The argument has the syntactic form of an expression, meeting the
1005 syntactic requirements for pragmas.
1007 If assertions are not enabled on the command line, this pragma has no
1008 effect. If asserts are enabled, the semantics of the pragma is exactly
1009 equivalent to the procedure call statement corresponding to the argument
1010 with a terminating semicolon. Pragmas are permitted in sequences of
1011 declarations, so you can use pragma @code{Debug} to intersperse calls to
1012 debug procedures in the middle of declarations.
1014 @cindex Elaboration control
1015 @findex Elaboration_Checks
1016 @item pragma Elaboration_Checks
1021 pragma Elaboration_Checks (RM | Static);
1025 This is a configuration pragma that provides control over the
1026 elaboration model used by the compilation affected by the
1027 pragma. If the parameter is RM, then the dynamic elaboration
1028 model described in the Ada Reference Manual is used, as though
1029 the @code{-gnatE} switch had been specified on the command
1030 line. If the parameter is Static, then the default GNAT static
1031 model is used. This configuration pragma overrides the setting
1032 of the command line. For full details on the elaboration models
1033 used by the GNAT compiler, see section ``Elaboration Order
1034 Handling in GNAT'' in the @cite{GNAT User's Guide}.
1036 @cindex Elimination of unused subprograms
1038 @item pragma Eliminate
1044 [Unit_Name =>] IDENTIFIER |
1045 SELECTED_COMPONENT);
1048 [Unit_Name =>] IDENTIFIER |
1050 [Entity =>] IDENTIFIER |
1051 SELECTED_COMPONENT |
1053 [,[Parameter_Types =>] PARAMETER_TYPES]
1054 [,[Result_Type =>] result_SUBTYPE_NAME]
1055 [,[Homonym_Number =>] INTEGER_LITERAL]);
1057 PARAMETER_TYPES ::= (SUBTYPE_NAME @{, SUBTYPE_NAME@})
1058 SUBTYPE_NAME ::= STRING_LITERAL
1062 This pragma indicates that the given entity is not used outside the
1063 compilation unit it is defined in. The entity may be either a subprogram
1066 If the entity to be eliminated is a library level subprogram, then
1067 the first form of pragma @code{Eliminate} is used with only a single argument.
1068 In this form, the @code{Unit_Name} argument specifies the name of the
1069 library level unit to be eliminated.
1071 In all other cases, both @code{Unit_Name} and @code{Entity} arguments
1072 are required. item is an entity of a library package, then the first
1073 argument specifies the unit name, and the second argument specifies
1074 the particular entity. If the second argument is in string form, it must
1075 correspond to the internal manner in which GNAT stores entity names (see
1076 compilation unit Namet in the compiler sources for details).
1078 The remaining parameters are optionally used to distinguish
1079 between overloaded subprograms. There are two ways of doing this.
1081 Use @code{Parameter_Types} and @code{Result_Type} to specify the
1082 profile of the subprogram to be eliminated in a manner similar to that
1084 the extended @code{Import} and @code{Export} pragmas, except that the
1085 subtype names are always given as string literals, again corresponding
1086 to the internal manner in which GNAT stores entity names.
1088 Alternatively, the @code{Homonym_Number} parameter is used to specify
1089 which overloaded alternative is to be eliminated. A value of 1 indicates
1090 the first subprogram (in lexical order), 2 indicates the second etc.
1092 The effect of the pragma is to allow the compiler to eliminate
1093 the code or data associated with the named entity. Any reference to
1094 an eliminated entity outside the compilation unit it is defined in,
1095 causes a compile time or link time error.
1097 The parameters of this pragma may be given in any order, as long as
1098 the usual rules for use of named parameters and position parameters
1101 The intention of pragma @code{Eliminate} is to allow a program to be compiled
1102 in a system independent manner, with unused entities eliminated, without
1103 the requirement of modifying the source text. Normally the required set
1104 of @code{Eliminate} pragmas is constructed automatically using the gnatelim tool.
1105 Elimination of unused entities local to a compilation unit is automatic,
1106 without requiring the use of pragma @code{Eliminate}.
1108 Note that the reason this pragma takes string literals where names might
1109 be expected is that a pragma @code{Eliminate} can appear in a context where the
1110 relevant names are not visible.
1113 @findex Export_Exception
1114 @item pragma Export_Exception
1119 pragma Export_Exception (
1120 [Internal =>] LOCAL_NAME,
1121 [, [External =>] EXTERNAL_SYMBOL,]
1122 [, [Form =>] Ada | VMS]
1123 [, [Code =>] static_integer_EXPRESSION]);
1127 | static_string_EXPRESSION
1131 This pragma is implemented only in the OpenVMS implementation of GNAT@. It
1132 causes the specified exception to be propagated outside of the Ada program,
1133 so that it can be handled by programs written in other OpenVMS languages.
1134 This pragma establishes an external name for an Ada exception and makes the
1135 name available to the OpenVMS Linker as a global symbol. For further details
1136 on this pragma, see the
1137 DEC Ada Language Reference Manual, section 13.9a3.2.
1139 @cindex Argument passing mechanisms
1140 @findex Export_Function
1141 @item pragma Export_Function @dots{}
1147 pragma Export_Function (
1148 [Internal =>] LOCAL_NAME,
1149 [, [External =>] EXTERNAL_SYMBOL]
1150 [, [Parameter_Types =>] PARAMETER_TYPES]
1151 [, [Result_Type =>] result_SUBTYPE_MARK]
1152 [, [Mechanism =>] MECHANISM]
1153 [, [Result_Mechanism =>] MECHANISM_NAME]);
1157 | static_string_EXPRESSION
1161 | SUBTYPE_MARK @{, SUBTYPE_MARK@}
1165 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1167 MECHANISM_ASSOCIATION ::=
1168 [formal_parameter_NAME =>] MECHANISM_NAME
1173 | Descriptor [([Class =>] CLASS_NAME)]
1175 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
1178 Use this pragma to make a function externally callable and optionally
1179 provide information on mechanisms to be used for passing parameter and
1180 result values. We recommend, for the purposes of improving portability,
1181 this pragma always be used in conjunction with a separate pragma
1182 @code{Export}, which must precede the pragma @code{Export_Function}.
1183 GNAT does not require a separate pragma @code{Export}, but if none is
1184 present, @code{Convention Ada} is assumed, which is usually
1185 not what is wanted, so it is usually appropriate to use this
1186 pragma in conjunction with a @code{Export} or @code{Convention}
1187 pragma that specifies the desired foreign convention.
1188 Pragma @code{Export_Function}
1189 (and @code{Export}, if present) must appear in the same declarative
1190 region as the function to which they apply.
1192 @var{internal_name} must uniquely designate the function to which the
1193 pragma applies. If more than one function name exists of this name in
1194 the declarative part you must use the @code{Parameter_Types} and
1195 @code{Result_Type} parameters is mandatory to achieve the required
1196 unique designation. @var{subtype_ mark}s in these parameters must
1197 exactly match the subtypes in the corresponding function specification,
1198 using positional notation to match parameters with subtype marks.
1200 @cindex Passing by descriptor
1201 Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
1203 @findex Export_Object
1204 @item pragma Export_Object @dots{}
1209 pragma Export_Object
1210 [Internal =>] LOCAL_NAME,
1211 [, [External =>] EXTERNAL_SYMBOL]
1212 [, [Size =>] EXTERNAL_SYMBOL]
1216 | static_string_EXPRESSION
1219 This pragma designates an object as exported, and apart from the
1220 extended rules for external symbols, is identical in effect to the use of
1221 the normal @code{Export} pragma applied to an object. You may use a
1222 separate Export pragma (and you probably should from the point of view
1223 of portability), but it is not required. @var{Size} is syntax checked,
1224 but otherwise ignored by GNAT@.
1226 @findex Export_Procedure
1227 @item pragma Export_Procedure @dots{}
1232 pragma Export_Procedure (
1233 [Internal =>] LOCAL_NAME
1234 [, [External =>] EXTERNAL_SYMBOL]
1235 [, [Parameter_Types =>] PARAMETER_TYPES]
1236 [, [Mechanism =>] MECHANISM]);
1240 | static_string_EXPRESSION
1244 | SUBTYPE_MARK @{, SUBTYPE_MARK@}
1248 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1250 MECHANISM_ASSOCIATION ::=
1251 [formal_parameter_NAME =>] MECHANISM_NAME
1256 | Descriptor [([Class =>] CLASS_NAME)]
1258 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
1262 This pragma is identical to @code{Export_Function} except that it
1263 applies to a procedure rather than a function and the parameters
1264 @code{Result_Type} and @code{Result_Mechanism} are not permitted.
1265 GNAT does not require a separate pragma @code{Export}, but if none is
1266 present, @code{Convention Ada} is assumed, which is usually
1267 not what is wanted, so it is usually appropriate to use this
1268 pragma in conjunction with a @code{Export} or @code{Convention}
1269 pragma that specifies the desired foreign convention.
1271 @findex Export_Valued_Procedure
1272 @item pragma Export_Valued_Procedure
1277 pragma Export_Valued_Procedure (
1278 [Internal =>] LOCAL_NAME
1279 [, [External =>] EXTERNAL_SYMBOL]
1280 [, [Parameter_Types =>] PARAMETER_TYPES]
1281 [, [Mechanism =>] MECHANISM]);
1285 | static_string_EXPRESSION
1289 | SUBTYPE_MARK @{, SUBTYPE_MARK@}
1293 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1295 MECHANISM_ASSOCIATION ::=
1296 [formal_parameter_NAME =>] MECHANISM_NAME
1301 | Descriptor [([Class =>] CLASS_NAME)]
1303 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
1306 This pragma is identical to @code{Export_Procedure} except that the
1307 first parameter of @var{local_name}, which must be present, must be of
1308 mode @code{OUT}, and externally the subprogram is treated as a function
1309 with this parameter as the result of the function. GNAT provides for
1310 this capability to allow the use of @code{OUT} and @code{IN OUT}
1311 parameters in interfacing to external functions (which are not permitted
1313 GNAT does not require a separate pragma @code{Export}, but if none is
1314 present, @code{Convention Ada} is assumed, which is almost certainly
1315 not what is wanted since the whole point of this pragma is to interface
1316 with foreign language functions, so it is usually appropriate to use this
1317 pragma in conjunction with a @code{Export} or @code{Convention}
1318 pragma that specifies the desired foreign convention.
1320 @cindex @code{system}, extending
1322 @findex Extend_System
1323 @item pragma Extend_System
1328 pragma Extend_System ([Name =>] IDENTIFIER);
1332 This pragma is used to provide backwards compatibility with other
1333 implementations that extend the facilities of package @code{System}. In
1334 GNAT, @code{System} contains only the definitions that are present in
1335 the Ada 95 RM@. However, other implementations, notably the DEC Ada 83
1336 implementation, provide many extensions to package @code{System}.
1338 For each such implementation accommodated by this pragma, GNAT provides a
1339 package @code{Aux_@var{xxx}}, e.g.@: @code{Aux_DEC} for the DEC Ada 83
1340 implementation, which provides the required additional definitions. You
1341 can use this package in two ways. You can @code{with} it in the normal
1342 way and access entities either by selection or using a @code{use}
1343 clause. In this case no special processing is required.
1345 However, if existing code contains references such as
1346 @code{System.@var{xxx}} where @var{xxx} is an entity in the extended
1347 definitions provided in package @code{System}, you may use this pragma
1348 to extend visibility in @code{System} in a non-standard way that
1349 provides greater compatibility with the existing code. Pragma
1350 @code{Extend_System} is a configuration pragma whose single argument is
1351 the name of the package containing the extended definition
1352 (e.g.@: @code{Aux_DEC} for the DEC Ada case). A unit compiled under
1353 control of this pragma will be processed using special visibility
1354 processing that looks in package @code{System.Aux_@var{xxx}} where
1355 @code{Aux_@var{xxx}} is the pragma argument for any entity referenced in
1356 package @code{System}, but not found in package @code{System}.
1358 You can use this pragma either to access a predefined @code{System}
1359 extension supplied with the compiler, for example @code{Aux_DEC} or
1360 you can construct your own extension unit following the above
1361 definition. Note that such a package is a child of @code{System}
1362 and thus is considered part of the implementation. To compile
1363 it you will have to use the appropriate switch for compiling
1364 system units. See the GNAT User's Guide for details.
1367 @item pragma External
1373 [ Convention =>] convention_IDENTIFIER,
1374 [ Entity =>] local_NAME
1375 [, [External_Name =>] static_string_EXPRESSION ]
1376 [, [Link_Name =>] static_string_EXPRESSION ]);
1380 This pragma is identical in syntax and semantics to pragma
1381 @code{Export} as defined in the Ada Reference Manual. It is
1382 provided for compatibility with some Ada 83 compilers that
1383 used this pragma for exactly the same purposes as pragma
1384 @code{Export} before the latter was standardized.
1386 @cindex Dec Ada 83 casing compatibility
1387 @cindex External Names, casing
1388 @cindex Casing of External names
1389 @findex External_Name_Casing
1390 @item pragma External_Name_Casing
1395 pragma External_Name_Casing (
1396 Uppercase | Lowercase
1397 [, Uppercase | Lowercase | As_Is]);
1401 This pragma provides control over the casing of external names associated
1402 with Import and Export pragmas. There are two cases to consider:
1405 @item Implicit external names
1406 Implicit external names are derived from identifiers. The most common case
1407 arises when a standard Ada 95 Import or Export pragma is used with only two
1411 pragma Import (C, C_Routine);
1415 Since Ada is a case insensitive language, the spelling of the identifier in
1416 the Ada source program does not provide any information on the desired
1417 casing of the external name, and so a convention is needed. In GNAT the
1418 default treatment is that such names are converted to all lower case
1419 letters. This corresponds to the normal C style in many environments.
1420 The first argument of pragma @code{External_Name_Casing} can be used to
1421 control this treatment. If @code{Uppercase} is specified, then the name
1422 will be forced to all uppercase letters. If @code{Lowercase} is specified,
1423 then the normal default of all lower case letters will be used.
1425 This same implicit treatment is also used in the case of extended DEC Ada 83
1426 compatible Import and Export pragmas where an external name is explicitly
1427 specified using an identifier rather than a string.
1429 @item Explicit external names
1430 Explicit external names are given as string literals. The most common case
1431 arises when a standard Ada 95 Import or Export pragma is used with three
1435 pragma Import (C, C_Routine, "C_routine");
1439 In this case, the string literal normally provides the exact casing required
1440 for the external name. The second argument of pragma
1441 @code{External_Name_Casing} may be used to modify this behavior.
1442 If @code{Uppercase} is specified, then the name
1443 will be forced to all uppercase letters. If @code{Lowercase} is specified,
1444 then the name will be forced to all lowercase letters. A specification of
1445 @code{As_Is} provides the normal default behavior in which the casing is
1446 taken from the string provided.
1450 This pragma may appear anywhere that a pragma is valid. In particular, it
1451 can be used as a configuration pragma in the @file{gnat.adc} file, in which
1452 case it applies to all subsequent compilations, or it can be used as a program
1453 unit pragma, in which case it only applies to the current unit, or it can
1454 be used more locally to control individual Import/Export pragmas.
1456 It is primarily intended for use with OpenVMS systems, where many
1457 compilers convert all symbols to upper case by default. For interfacing to
1458 such compilers (e.g.@: the DEC C compiler), it may be convenient to use
1462 pragma External_Name_Casing (Uppercase, Uppercase);
1466 to enforce the upper casing of all external symbols.
1468 @findex Finalize_Storage_Only
1469 @item pragma Finalize_Storage_Only
1474 pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);
1478 This pragma allows the compiler not to emit a Finalize call for objects
1479 defined at the library level. This is mostly useful for types where
1480 finalization is only used to deal with storage reclamation since in most
1481 environments it is not necessary to reclaim memory just before terminating
1482 execution, hence the name.
1485 @findex Float_Representation
1486 @item pragma Float_Representation
1491 pragma Float_Representation (FLOAT_REP);
1493 FLOAT_REP ::= VAX_Float | IEEE_Float
1497 This pragma is implemented only in the OpenVMS implementation of GNAT@.
1498 It allows control over the internal representation chosen for the predefined
1499 floating point types declared in the packages @code{Standard} and
1500 @code{System}. For further details on this pragma, see the
1501 DEC Ada Language Reference Manual, section 3.5.7a. Note that to use this
1502 pragma, the standard runtime libraries must be recompiled. See the
1503 description of the @code{GNAT LIBRARY} command in the OpenVMS version
1504 of the GNAT Users Guide for details on the use of this command.
1512 pragma Ident (static_string_EXPRESSION);
1516 This pragma provides a string identification in the generated object file,
1517 if the system supports the concept of this kind of identification string.
1518 The maximum permitted length of the string literal is 31 characters.
1519 This pragma is allowed only in the outermost declarative part or
1520 declarative items of a compilation unit.
1522 On OpenVMS systems, the effect of the pragma is identical to the effect of
1523 the DEC Ada 83 pragma of the same name.
1526 @findex Import_Exception
1527 @item pragma Import_Exception
1532 pragma Import_Exception (
1533 [Internal =>] LOCAL_NAME,
1534 [, [External =>] EXTERNAL_SYMBOL,]
1535 [, [Form =>] Ada | VMS]
1536 [, [Code =>] static_integer_EXPRESSION]);
1540 | static_string_EXPRESSION
1544 This pragma is implemented only in the OpenVMS implementation of GNAT@.
1545 It allows OpenVMS conditions (for example, from OpenVMS system services or
1546 other OpenVMS languages) to be propagated to Ada programs as Ada exceptions.
1547 The pragma specifies that the exception associated with an exception
1548 declaration in an Ada program be defined externally (in non-Ada code).
1549 For further details on this pragma, see the
1550 DEC Ada Language Reference Manual, section 13.9a.3.1.
1552 @findex Import_Function
1553 @item pragma Import_Function @dots{}
1558 pragma Import_Function (
1559 [Internal =>] LOCAL_NAME,
1560 [, [External =>] EXTERNAL_SYMBOL]
1561 [, [Parameter_Types =>] PARAMETER_TYPES]
1562 [, [Result_Type =>] SUBTYPE_MARK]
1563 [, [Mechanism =>] MECHANISM]
1564 [, [Result_Mechanism =>] MECHANISM_NAME]
1565 [, [First_Optional_Parameter =>] IDENTIFIER]);
1569 | static_string_EXPRESSION
1573 | SUBTYPE_MARK @{, SUBTYPE_MARK@}
1577 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1579 MECHANISM_ASSOCIATION ::=
1580 [formal_parameter_NAME =>] MECHANISM_NAME
1585 | Descriptor [([Class =>] CLASS_NAME)]
1587 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
1590 This pragma is used in conjunction with a pragma @code{Import} to
1591 specify additional information for an imported function. The pragma
1592 @code{Import} (or equivalent pragma @code{Interface}) must precede the
1593 @code{Import_Function} pragma and both must appear in the same
1594 declarative part as the function specification.
1596 The @var{Internal_Name} argument must uniquely designate
1597 the function to which the
1598 pragma applies. If more than one function name exists of this name in
1599 the declarative part you must use the @code{Parameter_Types} and
1600 @var{Result_Type} parameters to achieve the required unique
1601 designation. Subtype marks in these parameters must exactly match the
1602 subtypes in the corresponding function specification, using positional
1603 notation to match parameters with subtype marks.
1605 You may optionally use the @var{Mechanism} and @var{Result_Mechanism}
1606 parameters to specify passing mechanisms for the
1607 parameters and result. If you specify a single mechanism name, it
1608 applies to all parameters. Otherwise you may specify a mechanism on a
1609 parameter by parameter basis using either positional or named
1610 notation. If the mechanism is not specified, the default mechanism
1614 @cindex Passing by descriptor
1615 Passing by descriptor is supported only on the to OpenVMS ports of GNAT@.
1617 @code{First_Optional_Parameter} applies only to OpenVMS ports of GNAT@.
1618 It specifies that the designated parameter and all following parameters
1619 are optional, meaning that they are not passed at the generated code
1620 level (this is distinct from the notion of optional parameters in Ada
1621 where the parameters are passed anyway with the designated optional
1622 parameters). All optional parameters must be of mode @code{IN} and have
1623 default parameter values that are either known at compile time
1624 expressions, or uses of the @code{'Null_Parameter} attribute.
1626 @findex Import_Object
1627 @item pragma Import_Object
1632 pragma Import_Object
1633 [Internal =>] LOCAL_NAME,
1634 [, [External =>] EXTERNAL_SYMBOL],
1635 [, [Size =>] EXTERNAL_SYMBOL])
1639 | static_string_EXPRESSION
1643 This pragma designates an object as imported, and apart from the
1644 extended rules for external symbols, is identical in effect to the use of
1645 the normal @code{Import} pragma applied to an object. Unlike the
1646 subprogram case, you need not use a separate @code{Import} pragma,
1647 although you may do so (and probably should do so from a portability
1648 point of view). @var{size} is syntax checked, but otherwise ignored by
1651 @findex Import_Procedure
1652 @item pragma Import_Procedure
1657 pragma Import_Procedure (
1658 [Internal =>] LOCAL_NAME,
1659 [, [External =>] EXTERNAL_SYMBOL]
1660 [, [Parameter_Types =>] PARAMETER_TYPES]
1661 [, [Mechanism =>] MECHANISM]
1662 [, [First_Optional_Parameter =>] IDENTIFIER]);
1666 | static_string_EXPRESSION
1670 | SUBTYPE_MARK @{, SUBTYPE_MARK@}
1674 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1676 MECHANISM_ASSOCIATION ::=
1677 [formal_parameter_NAME =>] MECHANISM_NAME
1682 | Descriptor [([Class =>] CLASS_NAME)]
1684 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
1688 This pragma is identical to @code{Import_Function} except that it
1689 applies to a procedure rather than a function and the parameters
1690 @code{Result_Type} and @code{Result_Mechanism} are not permitted.
1692 @findex Import_Valued_Procedure
1693 @item pragma Import_Valued_Procedure @dots{}
1698 pragma Import_Valued_Procedure (
1699 [Internal =>] LOCAL_NAME,
1700 [, [External =>] EXTERNAL_SYMBOL]
1701 [, [Parameter_Types =>] PARAMETER_TYPES]
1702 [, [Mechanism =>] MECHANISM]
1703 [, [First_Optional_Parameter =>] IDENTIFIER]);
1707 | static_string_EXPRESSION
1711 | SUBTYPE_MARK @{, SUBTYPE_MARK@}
1715 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1717 MECHANISM_ASSOCIATION ::=
1718 [formal_parameter_NAME =>] MECHANISM_NAME
1723 | Descriptor [([Class =>] CLASS_NAME)]
1725 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
1729 This pragma is identical to @code{Import_Procedure} except that the
1730 first parameter of @var{local_name}, which must be present, must be of
1731 mode @code{OUT}, and externally the subprogram is treated as a function
1732 with this parameter as the result of the function. The purpose of this
1733 capability is to allow the use of @code{OUT} and @code{IN OUT}
1734 parameters in interfacing to external functions (which are not permitted
1735 in Ada functions). You may optionally use the @code{Mechanism}
1736 parameters to specify passing mechanisms for the parameters.
1737 If you specify a single mechanism name, it applies to all parameters.
1738 Otherwise you may specify a mechanism on a parameter by parameter
1739 basis using either positional or named notation. If the mechanism is not
1740 specified, the default mechanism is used.
1742 Note that it is important to use this pragma in conjunction with a separate
1743 pragma Import that specifies the desired convention, since otherwise the
1744 default convention is Ada, which is almost certainly not what is required.
1746 @findex Initialize_Scalars
1747 @cindex debugging with Initialize_Scalars
1748 @item pragma Initialize_Scalars
1753 pragma Initialize_Scalars;
1757 This pragma is similar to @code{Normalize_Scalars} conceptually but has
1758 two important differences. First, there is no requirement for the pragma
1759 to be used uniformly in all units of a partition, in particular, it is fine
1760 to use this just for some or all of the application units of a partition,
1761 without needing to recompile the run-time library.
1763 In the case where some units are compiled with the pragma, and some without,
1764 then a declaration of a variable where the type is defined in package
1765 Standard or is locally declared will always be subject to initialization,
1766 as will any declaration of a scalar variable. For composite variables,
1767 whether the variable is initialized may also depend on whether the package
1768 in which the type of the variable is declared is compiled with the pragma.
1770 The other important difference is that there is control over the value used
1771 for initializing scalar objects. At bind time, you can select whether to
1772 initialize with invalid values (like Normalize_Scalars), or with high or
1773 low values, or with a specified bit pattern. See the users guide for binder
1774 options for specifying these cases.
1776 This means that you can compile a program, and then without having to
1777 recompile the program, you can run it with different values being used
1778 for initializing otherwise uninitialized values, to test if your program
1779 behavior depends on the choice. Of course the behavior should not change,
1780 and if it does, then most likely you have an erroneous reference to an
1781 uninitialized value.
1783 Note that pragma @code{Initialize_Scalars} is particularly useful in
1784 conjunction with the enhanced validity checking that is now provided
1785 in GNAT, which checks for invalid values under more conditions.
1786 Using this feature (see description of the @code{-gnatv} flag in the
1787 users guide) in conjunction with pragma @code{Initialize_Scalars}
1788 provides a powerful new tool to assist in the detection of problems
1789 caused by uninitialized variables.
1791 @findex Inline_Always
1792 @item pragma Inline_Always
1797 pragma Inline_Always (NAME [, NAME]);
1801 Similar to pragma @code{Inline} except that inlining is not subject to
1802 the use of option @code{-gnatn} for inter-unit inlining.
1804 @findex Inline_Generic
1805 @item pragma Inline_Generic
1810 pragma Inline_Generic (generic_package_NAME)
1814 This is implemented for compatibility with DEC Ada 83 and is recognized,
1815 but otherwise ignored, by GNAT@. All generic instantiations are inlined
1816 by default when using GNAT@.
1819 @item pragma Interface
1825 [Convention =>] convention_identifier,
1826 [Entity =>] local_name
1827 [, [External_Name =>] static_string_expression],
1828 [, [Link_Name =>] static_string_expression]);
1832 This pragma is identical in syntax and semantics to
1833 the standard Ada 95 pragma @code{Import}. It is provided for compatibility
1834 with Ada 83. The definition is upwards compatible both with pragma
1835 @code{Interface} as defined in the Ada 83 Reference Manual, and also
1836 with some extended implementations of this pragma in certain Ada 83
1839 @findex Interface_Name
1840 @item pragma Interface_Name
1845 pragma Interface_Name (
1846 [Entity =>] LOCAL_NAME
1847 [, [External_Name =>] static_string_EXPRESSION]
1848 [, [Link_Name =>] static_string_EXPRESSION]);
1852 This pragma provides an alternative way of specifying the interface name
1853 for an interfaced subprogram, and is provided for compatibility with Ada
1854 83 compilers that use the pragma for this purpose. You must provide at
1855 least one of @var{External_Name} or @var{Link_Name}.
1858 @item pragma License
1859 @cindex License checking
1864 pragma License (Unrestricted | GPL | Modified_GPL | Restricted);
1868 This pragma is provided to allow automated checking for appropriate license
1869 conditions with respect to the standard and modified GPL@. A pragma @code{License},
1870 which is a configuration pragma that typically appears at the start of a
1871 source file or in a separate @file{gnat.adc} file, specifies the licensing
1872 conditions of a unit as follows:
1876 This is used for a unit that can be freely used with no license restrictions.
1877 Examples of such units are public domain units, and units from the Ada
1881 This is used for a unit that is licensed under the unmodified GPL, and which
1882 therefore cannot be @code{with}'ed by a restricted unit.
1885 This is used for a unit licensed under the GNAT modified GPL that includes
1886 a special exception paragraph that specifically permits the inclusion of
1887 the unit in programs without requiring the entire program to be released
1888 under the GPL@. This is the license used for the GNAT run-time which ensures
1889 that the run-time can be used freely in any program without GPL concerns.
1892 This is used for a unit that is restricted in that it is not permitted to
1893 depend on units that are licensed under the GPL@. Typical examples are
1894 proprietary code that is to be released under more restrictive license
1895 conditions. Note that restricted units are permitted to @code{with} units
1896 which are licensed under the modified GPL (this is the whole point of the
1902 Normally a unit with no @code{License} pragma is considered to have an
1903 unknown license, and no checking is done. However, standard GNAT headers
1904 are recognized, and license information is derived from them as follows.
1908 A GNAT license header starts with a line containing 78 hyphens. The following
1909 comment text is searched for the appearence of any of the following strings.
1911 If the string ``GNU General Public License'' is found, then the unit is assumed
1912 to have GPL license, unless the string ``As a special exception'' follows, in
1913 which case the license is assumed to be modified GPL@.
1915 If one of the strings
1916 ``This specification is adapated from the Ada Semantic Interface'' or
1917 ``This specification is derived from the Ada Reference Manual'' is found
1918 then the unit is assumed to be unrestricted.
1922 These default actions means that a program with a restricted license pragma
1923 will automatically get warnings if a GPL unit is inappropriately
1924 @code{with}'ed. For example, the program:
1929 procedure Secret_Stuff is
1935 if compiled with pragma @code{License} (@code{Restricted}) in a
1936 @file{gnat.adc} file will generate the warning:
1941 >>> license of withed unit "Sem_Ch3" is incompatible
1943 2. with GNAT.Sockets;
1944 3. procedure Secret_Stuff is
1947 Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT
1948 compiler and is licensed under the
1949 GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT
1950 run time, and is therefore licensed under the modified GPL@.
1953 @item pragma Link_With
1958 pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@});
1962 This pragma is provided for compatibility with certain Ada 83 compilers.
1963 It has exactly the same effect as pragma @code{Linker_Options} except
1964 that spaces occurring within one of the string expressions are treated
1965 as separators. For example, in the following case:
1968 pragma Link_With ("-labc -ldef");
1972 results in passing the strings @code{-labc} and @code{-ldef} as two
1973 separate arguments to the linker. In addition pragma Link_With allows
1974 multiple arguments, with the same effect as successive pragmas.
1976 @findex Linker_Alias
1977 @item pragma Linker_Alias
1982 pragma Linker_Alias (
1983 [Entity =>] LOCAL_NAME
1984 [Alias =>] static_string_EXPRESSION);
1988 This pragma establishes a linker alias for the given named entity. For
1989 further details on the exact effect, consult the GCC manual.
1991 @findex Linker_Section
1992 @item pragma Linker_Section
1997 pragma Linker_Section (
1998 [Entity =>] LOCAL_NAME
1999 [Section =>] static_string_EXPRESSION);
2003 This pragma specifies the name of the linker section for the given entity.
2004 For further details on the exact effect, consult the GCC manual.
2007 @item pragma No_Run_Time
2016 This is a configuration pragma that makes sure the user code does not
2017 use nor need anything from the GNAT run time. This is mostly useful in
2018 context where code certification is required. Please consult the
2019 @cite{GNAT Pro High-Integrity Edition User's Guide} for additional information.
2021 @findex Normalize_Scalars
2022 @item pragma Normalize_Scalars
2027 pragma Normalize_Scalars;
2031 This is a language defined pragma which is fully implemented in GNAT@. The
2032 effect is to cause all scalar objects that are not otherwise initialized
2033 to be initialized. The initial values are implementation dependent and
2037 @item Standard.Character
2039 Objects whose root type is Standard.Character are initialized to
2040 Character'Last. This will be out of range of the subtype only if
2041 the subtype range excludes this value.
2043 @item Standard.Wide_Character
2045 Objects whose root type is Standard.Wide_Character are initialized to
2046 Wide_Character'Last. This will be out of range of the subtype only if
2047 the subtype range excludes this value.
2051 Objects of an integer type are initialized to base_type'First, where
2052 base_type is the base type of the object type. This will be out of range
2053 of the subtype only if the subtype range excludes this value. For example,
2054 if you declare the subtype:
2057 subtype Ityp is integer range 1 .. 10;
2061 then objects of type x will be initialized to Integer'First, a negative
2062 number that is certainly outside the range of subtype @code{Ityp}.
2065 Objects of all real types (fixed and floating) are initialized to
2066 base_type'First, where base_Type is the base type of the object type.
2067 This will be out of range of the subtype only if the subtype range
2068 excludes this value.
2071 Objects of a modular type are initialized to typ'Last. This will be out
2072 of range of the subtype only if the subtype excludes this value.
2074 @item Enumeration types
2075 Objects of an enumeration type are initialized to all one-bits, i.e.@: to
2076 the value @code{2 ** typ'Size - 1}. This will be out of range of the enumeration
2077 subtype in all cases except where the subtype contains exactly
2078 2**8, 2**16, or 2**32 elements.
2084 @item pragma Long_Float
2089 pragma Long_Float (FLOAT_FORMAT);
2091 FLOAT_FORMAT ::= D_Float | G_Float
2095 This pragma is implemented only in the OpenVMS implementation of GNAT@.
2096 It allows control over the internal representation chosen for the predefined
2097 type @code{Long_Float} and for floating point type representations with
2098 @code{digits} specified in the range 7 through 15.
2099 For further details on this pragma, see the
2100 @cite{DEC Ada Language Reference Manual}, section 3.5.7b. Note that to use this
2101 pragma, the standard runtime libraries must be recompiled. See the
2102 description of the @code{GNAT LIBRARY} command in the OpenVMS version
2103 of the GNAT User's Guide for details on the use of this command.
2105 @findex Machine_Attribute
2106 @item pragma Machine_Attribute @dots{}
2111 pragma Machine_Attribute (
2112 [Attribute_Name =>] string_EXPRESSION,
2113 [Entity =>] LOCAL_NAME);
2116 Machine dependent attributes can be specified for types and/or
2117 declarations. Currently only subprogram entities are supported. This
2118 pragma is semantically equivalent to
2119 @code{__attribute__((@var{string_expression}))} in GNU C,
2120 where @code{@var{string_expression}} is
2121 recognized by the GNU C macros @code{VALID_MACHINE_TYPE_ATTRIBUTE} and
2122 @code{VALID_MACHINE_DECL_ATTRIBUTE} which are defined in the
2123 configuration header file @file{tm.h} for each machine. See the GCC
2124 manual for further information.
2127 @findex Main_Storage
2128 @item pragma Main_Storage
2134 (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]);
2136 MAIN_STORAGE_OPTION ::=
2137 [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION
2138 | [TOP_GUARD =>] static_SIMPLE_EXPRESSION
2143 This pragma is provided for compatibility with OpenVMS Vax Systems. It has
2144 no effect in GNAT, other than being syntax checked. Note that the pragma
2145 also has no effect in DEC Ada 83 for OpenVMS Alpha Systems.
2148 @item pragma No_Return
2153 pragma No_Return (procedure_LOCAL_NAME);
2157 @var{procedure_local_NAME} must refer to one or more procedure
2158 declarations in the current declarative part. A procedure to which this
2159 pragma is applied may not contain any explicit @code{return} statements,
2160 and also may not contain any implicit return statements from falling off
2161 the end of a statement sequence. One use of this pragma is to identify
2162 procedures whose only purpose is to raise an exception.
2164 Another use of this pragma is to suppress incorrect warnings about
2165 missing returns in functions, where the last statement of a function
2166 statement sequence is a call to such a procedure.
2169 @item pragma Passive
2174 pragma Passive ([Semaphore | No]);
2178 Syntax checked, but otherwise ignored by GNAT@. This is recognized for
2179 compatibility with DEC Ada 83 implementations, where it is used within a
2180 task definition to request that a task be made passive. If the argument
2181 @code{Semaphore} is present, or no argument is omitted, then DEC Ada 83
2182 treats the pragma as an assertion that the containing task is passive
2183 and that optimization of context switch with this task is permitted and
2184 desired. If the argument @code{No} is present, the task must not be
2185 optimized. GNAT does not attempt to optimize any tasks in this manner
2186 (since protected objects are available in place of passive tasks).
2189 @item pragma Polling
2194 pragma Polling (ON | OFF);
2198 This pragma controls the generation of polling code. This is normally off.
2199 If @code{pragma Polling (ON)} is used then periodic calls are generated to
2200 the routine @code{Ada.Exceptions.Poll}. This routine is a separate unit in the
2201 runtime library, and can be found in file @file{a-excpol.adb}.
2203 Pragma @code{Polling} can appear as a configuration pragma (for example it can be
2204 placed in the @file{gnat.adc} file) to enable polling globally, or it can be used
2205 in the statement or declaration sequence to control polling more locally.
2207 A call to the polling routine is generated at the start of every loop and
2208 at the start of every subprogram call. This guarantees that the @code{Poll}
2209 routine is called frequently, and places an upper bound (determined by
2210 the complexity of the code) on the period between two @code{Poll} calls.
2212 The primary purpose of the polling interface is to enable asynchronous
2213 aborts on targets that cannot otherwise support it (for example Windows
2214 NT), but it may be used for any other purpose requiring periodic polling.
2215 The standard version is null, and can be replaced by a user program. This
2216 will require re-compilation of the @code{Ada.Exceptions} package that can be found
2217 in files @file{a-except.ads} and @file{a-except.adb}.
2219 A standard alternative unit (in file @file{4wexcpol.adb} in the standard GNAT
2220 distribution) is used to enable the asynchronous abort capability on
2221 targets that do not normally support the capability. The version of @code{Poll}
2222 in this file makes a call to the appropriate runtime routine to test for
2225 Note that polling can also be enabled by use of the @code{-gnatP} switch. See
2226 the @cite{GNAT User's Guide} for details.
2228 @findex Propagate_Exceptions
2229 @cindex Zero Cost Exceptions
2230 @item pragma Propagate_Exceptions
2235 pragma Propagate_Exceptions (subprogram_LOCAL_NAME);
2239 This pragma indicates that the given entity, which is the name of an
2240 imported foreign-language subprogram may receive an Ada exception,
2241 and that the exception should be propagated. It is relevant only if
2242 zero cost exception handling is in use, and is thus never needed if
2243 the alternative @code{longjmp} / @code{setjmp} implementation of exceptions is used
2244 (although it is harmless to use it in such cases).
2246 The implementation of fast exceptions always properly propagates
2247 exceptions through Ada code, as described in the Ada Reference Manual.
2248 However, this manual is silent about the propagation of exceptions
2249 through foreign code. For example, consider the
2250 situation where @code{P1} calls
2251 @code{P2}, and @code{P2} calls @code{P3}, where
2252 @code{P1} and @code{P3} are in Ada, but @code{P2} is in C@.
2253 @code{P3} raises an Ada exception. The question is whether or not
2254 it will be propagated through @code{P2} and can be handled in
2257 For the @code{longjmp} / @code{setjmp} implementation of exceptions, the answer is
2258 always yes. For some targets on which zero cost exception handling
2259 is implemented, the answer is also always yes. However, there are
2260 some targets, notably in the current version all x86 architecture
2261 targets, in which the answer is that such propagation does not
2262 happen automatically. If such propagation is required on these
2263 targets, it is mandatory to use @code{Propagate_Exceptions} to
2264 name all foreign language routines through which Ada exceptions
2267 @findex Psect_Object
2268 @item pragma Psect_Object
2274 [Internal =>] LOCAL_NAME,
2275 [, [External =>] EXTERNAL_SYMBOL]
2276 [, [Size =>] EXTERNAL_SYMBOL]
2280 | static_string_EXPRESSION
2284 This pragma is identical in effect to pragma @code{Common_Object}.
2286 @findex Pure_Function
2287 @item pragma Pure_Function
2292 pragma Pure_Function ([Entity =>] function_LOCAL_NAME);
2295 This pragma appears in the same declarative part as a function
2296 declaration (or a set of function declarations if more than one
2297 overloaded declaration exists, in which case the pragma applies
2298 to all entities). If specifies that the function @code{Entity} is
2299 to be considered pure for the purposes of code generation. This means
2300 that the compiler can assume that there are no side effects, and
2301 in particular that two calls with identical arguments produce the
2302 same result. It also means that the function can be used in an
2305 Note that, quite deliberately, there are no static checks to try
2306 to ensure that this promise is met, so @code{Pure_Function} can be used
2307 with functions that are conceptually pure, even if they do modify
2308 global variables. For example, a square root function that is
2309 instrumented to count the number of times it is called is still
2310 conceptually pure, and can still be optimized, even though it
2311 modifies a global variable (the count). Memo functions are another
2312 example (where a table of previous calls is kept and consulted to
2313 avoid re-computation).
2316 Note: Most functions in a @code{Pure} package are automatically pure, and
2317 there is no need to use pragma @code{Pure_Function} for such functions. An
2318 exception is any function that has at least one formal of type
2319 @code{System.Address} or a type derived from it. Such functions are not
2320 considered pure by default, since the compiler assumes that the
2321 @code{Address} parameter may be functioning as a pointer and that the
2322 referenced data may change even if the address value does not. The use
2323 of pragma @code{Pure_Function} for such a function will override this default
2324 assumption, and cause the compiler to treat such a function as pure.
2326 Note: If pragma @code{Pure_Function} is applied to a renamed function, it
2327 applies to the underlying renamed function. This can be used to
2328 disambiguate cases of overloading where some but not all functions
2329 in a set of overloaded functions are to be designated as pure.
2332 @item pragma Ravenscar
2341 A configuration pragma that establishes the following set of restrictions:
2344 @item No_Abort_Statements
2345 [RM D.7] There are no abort_statements, and there are
2346 no calls to Task_Identification.Abort_Task.
2348 @item No_Select_Statements
2349 There are no select_statements.
2351 @item No_Task_Hierarchy
2352 [RM D.7] All (non-environment) tasks depend
2353 directly on the environment task of the partition.
2355 @item No_Task_Allocators
2356 [RM D.7] There are no allocators for task types
2357 or types containing task subcomponents.
2359 @item No_Dynamic_Priorities
2360 [RM D.7] There are no semantic dependencies on the package Dynamic_Priorities.
2362 @item No_Terminate_Alternatives
2363 [RM D.7] There are no selective_accepts with terminate_alternatives
2365 @item No_Dynamic_Interrupts
2366 There are no semantic dependencies on Ada.Interrupts.
2368 @item No_Protected_Type_Allocators
2369 There are no allocators for protected types or
2370 types containing protected subcomponents.
2372 @item No_Local_Protected_Objects
2373 Protected objects and access types that designate
2374 such objects shall be declared only at library level.
2377 Requeue statements are not allowed.
2380 There are no semantic dependencies on the package Ada.Calendar.
2382 @item No_Relative_Delay
2383 There are no delay_relative_statements.
2385 @item No_Task_Attributes
2386 There are no semantic dependencies on the Ada.Task_Attributes package and
2387 there are no references to the attributes Callable and Terminated [RM 9.9].
2389 @item Static_Storage_Size
2390 The expression for pragma Storage_Size is static.
2392 @item Boolean_Entry_Barriers
2393 Entry barrier condition expressions shall be boolean
2394 objects which are declared in the protected type
2395 which contains the entry.
2397 @item Max_Asynchronous_Select_Nesting = 0
2398 [RM D.7] Specifies the maximum dynamic nesting level of asynchronous_selects.
2399 A value of zero prevents the use of any asynchronous_select.
2401 @item Max_Task_Entries = 0
2402 [RM D.7] Specifies the maximum number of entries
2403 per task. The bounds of every entry family
2404 of a task unit shall be static, or shall be
2405 defined by a discriminant of a subtype whose
2406 corresponding bound is static. A value of zero
2407 indicates that no rendezvous are possible. For
2408 the Ravenscar pragma, the value of Max_Task_Entries is always
2411 @item Max_Protected_Entries = 1
2412 [RM D.7] Specifies the maximum number of entries per
2413 protected type. The bounds of every entry family of
2414 a protected unit shall be static, or shall be defined
2415 by a discriminant of a subtype whose corresponding
2416 bound is static. For the Ravenscar pragma the value of
2417 Max_Protected_Entries is always 1.
2419 @item Max_Select_Alternatives = 0
2420 [RM D.7] Specifies the maximum number of alternatives in a selective_accept.
2421 For the Ravenscar pragma the value if always 0.
2423 @item No_Task_Termination
2424 Tasks which terminate are erroneous.
2426 @item No_Entry_Queue
2427 No task can be queued on a protected entry. Note that this restrictions is
2428 checked at run time. The violation of this restriction generates a
2429 Program_Error exception.
2433 This set of restrictions corresponds to the definition of the ``Ravenscar
2434 Profile'' for limited tasking, devised and published by the @cite{International
2435 Real-Time Ada Workshop}, 1997.
2437 The above set is a superset of the restrictions provided by pragma
2438 @code{Restricted_Run_Time}, it includes six additional restrictions
2439 (@code{Boolean_Entry_Barriers}, @code{No_Select_Statements},
2440 @code{No_Calendar}, @code{Static_Storage_Size},
2441 @code{No_Relative_Delay} and @code{No_Task_Termination}). This means
2442 that pragma @code{Ravenscar}, like the pragma @code{Restricted_Run_Time}, automatically
2443 causes the use of a simplified, more efficient version of the tasking
2446 @findex Restricted_Run_Time
2447 @item pragma Restricted_Run_Time
2452 pragma Restricted_Run_Time
2456 A configuration pragma that establishes the following set of restrictions:
2459 @item No_Abort_Statements
2460 @item No_Asynchronous_Control
2461 @item No_Entry_Queue
2462 @item No_Task_Hierarchy
2463 @item No_Task_Allocators
2464 @item No_Dynamic_Priorities
2465 @item No_Terminate_Alternatives
2466 @item No_Dynamic_Interrupts
2467 @item No_Protected_Type_Allocators
2468 @item No_Local_Protected_Objects
2470 @item No_Task_Attributes
2471 @item Max_Asynchronous_Select_Nesting = 0
2472 @item Max_Task_Entries = 0
2473 @item Max_Protected_Entries = 1
2474 @item Max_Select_Alternatives = 0
2478 This set of restrictions causes the automatic selection of a simplified
2479 version of the run time that provides improved performance for the
2480 limited set of tasking functionality permitted by this set of restrictions.
2482 @findex Share_Generic
2483 @item pragma Share_Generic
2488 pragma Share_Generic (NAME @{, NAME@});
2492 This pragma is recognized for compatibility with other Ada compilers
2493 but is ignored by GNAT@. GNAT does not provide the capability for
2494 sharing of generic code. All generic instantiations result in making
2495 an inlined copy of the template with appropriate substitutions.
2497 @findex Source_File_Name
2498 @item pragma Source_File_Name
2503 pragma Source_File_Name (
2504 [Unit_Name =>] unit_NAME,
2505 Spec_File_Name => STRING_LITERAL);
2507 pragma Source_File_Name (
2508 [Unit_Name =>] unit_NAME,
2509 Body_File_Name => STRING_LITERAL);
2513 Use this to override the normal naming convention. It is a configuration
2514 pragma, and so has the usual applicability of configuration pragmas
2515 (i.e.@: it applies to either an entire partition, or to all units in a
2516 compilation, or to a single unit, depending on how it is used.
2517 @var{unit_name} is mapped to @var{file_name_literal}. The identifier for
2518 the second argument is required, and indicates whether this is the file
2519 name for the spec or for the body.
2521 Another form of the @code{Source_File_Name} pragma allows
2522 the specification of patterns defining alternative file naming schemes
2523 to apply to all files.
2526 pragma Source_File_Name
2527 (Spec_File_Name => STRING_LITERAL
2528 [,Casing => CASING_SPEC]
2529 [,Dot_Replacement => STRING_LITERAL]);
2531 pragma Source_File_Name
2532 (Body_File_Name => STRING_LITERAL
2533 [,Casing => CASING_SPEC]
2534 [,Dot_Replacement => STRING_LITERAL]);
2536 pragma Source_File_Name
2537 (Subunit_File_Name => STRING_LITERAL
2538 [,Casing => CASING_SPEC]
2539 [,Dot_Replacement => STRING_LITERAL]);
2541 CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
2545 The first argument is a pattern that contains a single asterisk indicating
2546 the point at which the unit name is to be inserted in the pattern string
2547 to form the file name. The second argument is optional. If present it
2548 specifies the casing of the unit name in the resulting file name string.
2549 The default is lower case. Finally the third argument allows for systematic
2550 replacement of any dots in the unit name by the specified string literal.
2552 For more details on the use of the @code{Source_File_Name} pragma,
2553 see the sections ``Using Other File Names'' and
2554 ``Alternative File Naming Schemes'' in the @cite{GNAT User's Guide}.
2556 @findex Source_Reference
2557 @item pragma Source_Reference
2562 pragma Source_Reference (INTEGER_LITERAL,
2567 This pragma must appear as the first line of a source file.
2568 @var{integer_literal} is the logical line number of the line following
2569 the pragma line (for use in error messages and debugging
2570 information). @var{string_literal} is a static string constant that
2571 specifies the file name to be used in error messages and debugging
2572 information. This is most notably used for the output of @code{gnatchop}
2573 with the @code{-r} switch, to make sure that the original unchopped
2574 source file is the one referred to.
2576 The second argument must be a string literal, it cannot be a static
2577 string expression other than a string literal. This is because its value
2578 is needed for error messages issued by all phases of the compiler.
2580 @findex Stream_Convert
2581 @item pragma Stream_Convert
2586 pragma Stream_Convert (
2587 [Entity =>] type_LOCAL_NAME,
2588 [Read =>] function_NAME,
2589 [Write =>] function NAME);
2593 This pragma provides an efficient way of providing stream functions for
2594 types defined in packages. Not only is it simpler to use than declaring
2595 the necessary functions with attribute representation clauses, but more
2596 significantly, it allows the declaration to made in such a way that the
2597 stream packages are not loaded unless they are needed. The use of
2598 the Stream_Convert pragma adds no overhead at all, unless the stream
2599 attributes are actually used on the designated type.
2601 The first argument specifies the type for which stream functions are
2602 provided. The second parameter provides a function used to read values
2603 of this type. It must name a function whose argument type may be any
2604 subtype, and whose returned type must be the type given as the first
2605 argument to the pragma.
2607 The meaning of the @var{Read}
2608 parameter is that if a stream attribute directly
2609 or indirectly specifies reading of the type given as the first parameter,
2610 then a value of the type given as the argument to the Read function is
2611 read from the stream, and then the Read function is used to convert this
2612 to the required target type.
2614 Similarly the @var{Write} parameter specifies how to treat write attributes
2615 that directly or indirectly apply to the type given as the first parameter.
2616 It must have an input parameter of the type specified by the first parameter,
2617 and the return type must be the same as the input type of the Read function.
2618 The effect is to first call the Write function to convert to the given stream
2619 type, and then write the result type to the stream.
2621 The Read and Write functions must not be overloaded subprograms. If necessary
2622 renamings can be supplied to meet this requirement.
2623 The usage of this attribute is best illustrated by a simple example, taken
2624 from the GNAT implementation of package Ada.Strings.Unbounded:
2627 function To_Unbounded (S : String)
2628 return Unbounded_String
2629 renames To_Unbounded_String;
2631 pragma Stream_Convert
2632 (Unbounded_String, To_Unbounded, To_String);
2636 The specifications of the referenced functions, as given in the Ada 95
2637 Reference Manual are:
2640 function To_Unbounded_String (Source : String)
2641 return Unbounded_String;
2643 function To_String (Source : Unbounded_String)
2648 The effect is that if the value of an unbounded string is written to a
2649 stream, then the representation of the item in the stream is in the same
2650 format used for @code{Standard.String}, and this same representation is
2651 expected when a value of this type is read from the stream.
2653 @findex Style_Checks
2654 @item pragma Style_Checks
2659 pragma Style_Checks (string_LITERAL | ALL_CHECKS |
2660 On | Off [, LOCAL_NAME]);
2664 This pragma is used in conjunction with compiler switches to control the
2665 built in style checking provided by GNAT@. The compiler switches, if set
2666 provide an initial setting for the switches, and this pragma may be used
2667 to modify these settings, or the settings may be provided entirely by
2668 the use of the pragma. This pragma can be used anywhere that a pragma
2669 is legal, including use as a configuration pragma (including use in
2670 the @file{gnat.adc} file).
2672 The form with a string literal specifies which style options are to be
2673 activated. These are additive, so they apply in addition to any previously
2674 set style check options. The codes for the options are the same as those
2675 used in the @code{-gnaty} switch to @code{gcc} or @code{gnatmake}.
2676 For example the following two methods can be used to enable
2680 pragma Style_Checks ("l");
2681 gcc -c -gnatyl @dots{}
2685 The form ALL_CHECKS activates all standard checks (its use is equivalent
2686 to the use of the @code{gnaty} switch with no options. See GNAT User's
2689 The forms with @code{Off} and @code{On}
2690 can be used to temporarily disable style checks
2691 as shown in the following example:
2697 pragma Style_Checks ("k"); -- requires keywords in lower case
2698 pragma Style_Checks (Off); -- turn off style checks
2699 NULL; -- this will not generate an error message
2700 pragma Style_Checks (On); -- turn style checks back on
2701 NULL; -- this will generate an error message
2705 Finally the two argument form is allowed only if the first argument is
2706 @code{On} or @code{Off}. The effect is to turn of semantic style checks
2707 for the specified entity, as shown in the following example:
2713 pragma Style_Checks ("r"); -- require consistency of identifier casing
2715 Rf1 : Integer := ARG; -- incorrect, wrong case
2716 pragma Style_Checks (Off, Arg);
2717 Rf2 : Integer := ARG; -- OK, no error
2721 @item pragma Subtitle
2726 pragma Subtitle ([Subtitle =>] STRING_LITERAL);
2730 This pragma is recognized for compatibility with other Ada compilers
2731 but is ignored by GNAT@.
2733 @findex Suppress_All
2734 @item pragma Suppress_All
2739 pragma Suppress_All;
2743 This pragma can only appear immediately following a compilation
2744 unit. The effect is to apply @code{Suppress (All_Checks)} to the unit
2745 which it follows. This pragma is implemented for compatibility with DEC
2746 Ada 83 usage. The use of pragma @code{Suppress (All_Checks)} as a normal
2747 configuration pragma is the preferred usage in GNAT@.
2749 @findex Suppress_Initialization
2750 @cindex Suppressing initialization
2751 @cindex Initialization, suppression of
2752 @item pragma Suppress_Initialization
2757 pragma Suppress_Initialization ([Entity =>] type_Name);
2761 This pragma suppresses any implicit or explicit initialization
2762 associated with the given type name for all variables of this type.
2765 @item pragma Task_Info
2770 pragma Task_Info (EXPRESSION);
2774 This pragma appears within a task definition (like pragma
2775 @code{Priority}) and applies to the task in which it appears. The
2776 argument must be of type @code{System.Task_Info.Task_Info_Type}.
2777 The @code{Task_Info} pragma provides system dependent control over
2778 aspect of tasking implementation, for example, the ability to map
2779 tasks to specific processors. For details on the facilities available
2780 for the version of GNAT that you are using, see the documentation
2781 in the specification of package System.Task_Info in the runtime
2785 @item pragma Task_Name
2790 pragma Task_Name (string_EXPRESSION);
2794 This pragma appears within a task definition (like pragma
2795 @code{Priority}) and applies to the task in which it appears. The
2796 argument must be of type String, and provides a name to be used for
2797 the task instance when the task is created. Note that this expression
2798 is not required to be static, and in particular, it can contain
2799 references to task discriminants. This facility can be used to
2800 provide different names for different tasks as they are created,
2801 as illustrated in the example below.
2803 The task name is recorded internally in the run-time structures
2804 and is accessible to tools like the debugger. In addition the
2805 routine @code{Ada.Task_Identification.Image} will return this
2806 string, with a unique task address appended.
2809 -- Example of the use of pragma Task_Name
2811 with Ada.Task_Identification;
2812 use Ada.Task_Identification;
2813 with Text_IO; use Text_IO;
2816 type Astring is access String;
2818 task type Task_Typ (Name : access String) is
2819 pragma Task_Name (Name.all);
2822 task body Task_Typ is
2823 Nam : constant String := Image (Current_Task);
2825 Put_Line ("-->" & Nam (1 .. 14) & "<--");
2828 type Ptr_Task is access Task_Typ;
2829 Task_Var : Ptr_Task;
2833 new Task_Typ (new String'("This is task 1"));
2835 new Task_Typ (new String'("This is task 2"));
2839 @findex Task_Storage
2840 @item pragma Task_Storage
2845 [Task_Type =>] LOCAL_NAME,
2846 [Top_Guard =>] static_integer_EXPRESSION);
2849 This pragma specifies the length of the guard area for tasks. The guard
2850 area is an additional storage area allocated to a task. A value of zero
2851 means that either no guard area is created or a minimal guard area is
2852 created, depending on the target. This pragma can appear anywhere a
2853 @code{Storage_Size} attribute definition clause is allowed for a task
2857 @item pragma Time_Slice
2862 pragma Time_Slice (static_duration_EXPRESSION);
2866 For implementations of GNAT on operating systems where it is possible
2867 to supply a time slice value, this pragma may be used for this purpose.
2868 It is ignored if it is used in a system that does not allow this control,
2869 or if it appears in other than the main program unit.
2871 Note that the effect of this pragma is identical to the effect of the
2872 DEC Ada 83 pragma of the same name when operating under OpenVMS systems.
2880 pragma Title (TITLING_OPTION [, TITLING OPTION]);
2883 [Title =>] STRING_LITERAL,
2884 | [Subtitle =>] STRING_LITERAL
2888 Syntax checked but otherwise ignored by GNAT@. This is a listing control
2889 pragma used in DEC Ada 83 implementations to provide a title and/or
2890 subtitle for the program listing. The program listing generated by GNAT
2891 does not have titles or subtitles.
2893 Unlike other pragmas, the full flexibility of named notation is allowed
2894 for this pragma, i.e.@: the parameters may be given in any order if named
2895 notation is used, and named and positional notation can be mixed
2896 following the normal rules for procedure calls in Ada.
2899 @findex Unchecked_Union
2900 @item pragma Unchecked_Union
2905 pragma Unchecked_Union (first_subtype_LOCAL_NAME)
2909 This pragma is used to declare that the specified type should be represented
2911 equivalent to a C union type, and is intended only for use in
2912 interfacing with C code that uses union types. In Ada terms, the named
2913 type must obey the following rules:
2917 It is a non-tagged non-limited record type.
2919 It has a single discrete discriminant with a default value.
2921 The component list consists of a single variant part.
2923 Each variant has a component list with a single component.
2925 No nested variants are allowed.
2927 No component has an explicit default value.
2929 No component has a non-static constraint.
2932 In addition, given a type that meets the above requirements, the
2933 following restrictions apply to its use throughout the program:
2937 The discriminant name can be mentioned only in an aggregate.
2939 No subtypes may be created of this type.
2941 The type may not be constrained by giving a discriminant value.
2943 The type cannot be passed as the actual for a generic formal with a
2947 Equality and inequality operations on @code{unchecked_unions} are not
2948 available, since there is no discriminant to compare and the compiler
2949 does not even know how many bits to compare. It is implementation
2950 dependent whether this is detected at compile time as an illegality or
2951 whether it is undetected and considered to be an erroneous construct. In
2952 GNAT, a direct comparison is illegal, but GNAT does not attempt to catch
2953 the composite case (where two composites are compared that contain an
2954 unchecked union component), so such comparisons are simply considered
2957 The layout of the resulting type corresponds exactly to a C union, where
2958 each branch of the union corresponds to a single variant in the Ada
2959 record. The semantics of the Ada program is not changed in any way by
2960 the pragma, i.e.@: provided the above restrictions are followed, and no
2961 erroneous incorrect references to fields or erroneous comparisons occur,
2962 the semantics is exactly as described by the Ada reference manual.
2963 Pragma @code{Suppress (Discriminant_Check)} applies implicitly to the
2964 type and the default convention is C
2966 @findex Unimplemented_Unit
2967 @item pragma Unimplemented_Unit
2972 pragma Unimplemented_Unit;
2976 If this pragma occurs in a unit that is processed by the compiler, GNAT
2977 aborts with the message @samp{@var{xxx} not implemented}, where
2978 @var{xxx} is the name of the current compilation unit. This pragma is
2979 intended to allow the compiler to handle unimplemented library units in
2982 The abort only happens if code is being generated. Thus you can use
2983 specs of unimplemented packages in syntax or semantic checking mode.
2985 @findex Unreferenced
2986 @item pragma Unreferenced
2987 @cindex Warnings, unreferenced
2992 pragma Unreferenced (local_Name @{, local_Name@});
2996 This pragma signals that the entities whose names are listed are
2997 deliberately not referenced. This suppresses warnings about the
2998 entities being unreferenced, and in addition a warning will be
2999 generated if one of these entities is in fact referenced.
3001 This is particularly useful for clearly signalling that a particular
3002 parameter is not referenced in some particular subprogram implementation
3003 and that this is deliberate. It can also be useful in the case of
3004 objects declared only for their initialization or finalization side
3007 If @code{local_Name} identifies more than one matching homonym in the
3008 current scope, then the entity most recently declared is the one to which
3011 @findex Unreserve_All_Interrupts
3012 @item pragma Unreserve_All_Interrupts
3017 pragma Unreserve_All_Interrupts;
3021 Normally certain interrupts are reserved to the implementation. Any attempt
3022 to attach an interrupt causes Program_Error to be raised, as described in
3023 RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
3024 many systems for an @kbd{Ctrl-C} interrupt. Normally this interrupt is
3025 reserved to the implementation, so that @kbd{Ctrl-C} can be used to
3026 interrupt execution.
3028 If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in
3029 a program, then all such interrupts are unreserved. This allows the
3030 program to handle these interrupts, but disables their standard
3031 functions. For example, if this pragma is used, then pressing
3032 @kbd{Ctrl-C} will not automatically interrupt execution. However,
3033 a program can then handle the @code{SIGINT} interrupt as it chooses.
3035 For a full list of the interrupts handled in a specific implementation,
3036 see the source code for the specification of @code{Ada.Interrupts.Names} in
3037 file @file{a-intnam.ads}. This is a target dependent file that contains the
3038 list of interrupts recognized for a given target. The documentation in
3039 this file also specifies what interrupts are affected by the use of
3040 the @code{Unreserve_All_Interrupts} pragma.
3043 @item pragma Unsuppress
3048 pragma Unsuppress (IDENTIFIER [, [On =>] NAME]);
3052 This pragma undoes the effect of a previous pragma @code{Suppress}. If
3053 there is no corresponding pragma @code{Suppress} in effect, it has no
3054 effect. The range of the effect is the same as for pragma
3055 @code{Suppress}. The meaning of the arguments is identical to that used
3056 in pragma @code{Suppress}.
3058 One important application is to ensure that checks are on in cases where
3059 code depends on the checks for its correct functioning, so that the code
3060 will compile correctly even if the compiler switches are set to suppress
3063 @cindex @code{Size}, VADS compatibility
3064 @findex Use_VADS_Size
3065 @item pragma Use_VADS_Size
3070 pragma Use_VADS_Size;
3074 This is a configuration pragma. In a unit to which it applies, any use
3075 of the 'Size attribute is automatically interpreted as a use of the
3076 'VADS_Size attribute. Note that this may result in incorrect semantic
3077 processing of valid Ada 95 programs. This is intended to aid in the
3078 handling of legacy code which depends on the interpretation of Size
3079 as implemented in the VADS compiler. See description of the VADS_Size
3080 attribute for further details.
3082 @findex Validity_Checks
3083 @item pragma Validity_Checks
3088 pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off);
3092 This pragma is used in conjunction with compiler switches to control the
3093 built in validity checking provided by GNAT@. The compiler switches, if set
3094 provide an initial setting for the switches, and this pragma may be used
3095 to modify these settings, or the settings may be provided entirely by
3096 the use of the pragma. This pragma can be used anywhere that a pragma
3097 is legal, including use as a configuration pragma (including use in
3098 the @file{gnat.adc} file).
3100 The form with a string literal specifies which validity options are to be
3101 activated. The validity checks are first set to include only the default
3102 reference manual settings, and then a string of letters in the string
3103 specifies the exact set of options required. The form of this string
3104 is exactly as described for the @code{-gnatVx} compiler switch (see the
3105 GNAT users guide for details). For example the following two methods
3106 can be used to enable validity checking for mode @code{in} and
3107 @code{in out} subprogram parameters:
3110 pragma Validity_Checks ("im");
3111 gcc -c -gnatVim @dots{}
3115 The form ALL_CHECKS activates all standard checks (its use is equivalent
3116 to the use of the @code{gnatva} switch.
3118 The forms with @code{Off} and @code{On}
3119 can be used to temporarily disable validity checks
3120 as shown in the following example:
3126 pragma Validity_Checks ("c"); -- validity checks for copies
3127 pragma Validity_Checks (Off); -- turn off validity checks
3128 A := B; -- B will not be validity checked
3129 pragma Validity_Checks (On); -- turn validity checks back on
3130 A := C; -- C will be validity checked
3134 @item pragma Volatile
3139 pragma Volatile (local_NAME)
3143 This pragma is defined by the Ada 95 Reference Manual, and the GNAT
3144 implementation is fully conformant with this definition. The reason it
3145 is mentioned in this section is that a pragma of the same name was supplied
3146 in some Ada 83 compilers, including DEC Ada 83. The Ada 95 implementation
3147 of pragma Volatile is upwards compatible with the implementation in
3151 @item pragma Warnings
3156 pragma Warnings (On | Off [, LOCAL_NAME]);
3160 Normally warnings are enabled, with the output being controlled by
3161 the command line switch. Warnings (@code{Off}) turns off generation of
3162 warnings until a Warnings (@code{On}) is encountered or the end of the
3163 current unit. If generation of warnings is turned off using this
3164 pragma, then no warning messages are output, regardless of the
3165 setting of the command line switches.
3167 The form with a single argument is a configuration pragma.
3169 If the @var{local_name} parameter is present, warnings are suppressed for
3170 the specified entity. This suppression is effective from the point where
3171 it occurs till the end of the extended scope of the variable (similar to
3172 the scope of @code{Suppress}).
3174 @findex Weak_External
3175 @item pragma Weak_External
3180 pragma Weak_External ([Entity =>] LOCAL_NAME);
3184 This pragma specifies that the given entity should be marked as a weak
3185 external (one that does not have to be resolved) for the linker. For
3186 further details, consult the GCC manual.
3189 @node Implementation Defined Attributes
3190 @chapter Implementation Defined Attributes
3191 Ada 95 defines (throughout the Ada 95 reference manual,
3192 summarized in annex K),
3193 a set of attributes that provide useful additional functionality in all
3194 areas of the language. These language defined attributes are implemented
3195 in GNAT and work as described in the Ada 95 Reference Manual.
3197 In addition, Ada 95 allows implementations to define additional
3198 attributes whose meaning is defined by the implementation. GNAT provides
3199 a number of these implementation-dependent attributes which can be used
3200 to extend and enhance the functionality of the compiler. This section of
3201 the GNAT reference manual describes these additional attributes.
3203 Note that any program using these attributes may not be portable to
3204 other compilers (although GNAT implements this set of attributes on all
3205 platforms). Therefore if portability to other compilers is an important
3206 consideration, you should minimize the use of these attributes.
3209 @findex Abort_Signal
3212 @code{Standard'Abort_Signal} (@code{Standard} is the only allowed
3213 prefix) provides the entity for the special exception used to signal
3214 task abort or asynchronous transfer of control. Normally this attribute
3215 should only be used in the tasking runtime (it is highly peculiar, and
3216 completely outside the normal semantics of Ada, for a user program to
3217 intercept the abort exception).
3219 @cindex Size of @code{Address}
3220 @findex Address_Size
3223 @code{Standard'Address_Size} (@code{Standard} is the only allowed
3224 prefix) is a static constant giving the number of bits in an
3225 @code{Address}. It is used primarily for constructing the definition of
3226 @code{Memory_Size} in package @code{Standard}, but may be freely used in user
3227 programs and has the advantage of being static, while a direct
3228 reference to System.Address'Size is non-static because Address
3234 The @code{Asm_Input} attribute denotes a function that takes two
3235 parameters. The first is a string, the second is an expression of the
3236 type designated by the prefix. The first (string) argument is required
3237 to be a static expression, and is the constraint for the parameter,
3238 (e.g.@: what kind of register is required). The second argument is the
3239 value to be used as the input argument. The possible values for the
3240 constant are the same as those used in the RTL, and are dependent on
3241 the configuration file used to built the GCC back end.
3242 @ref{Machine Code Insertions}
3247 The @code{Asm_Output} attribute denotes a function that takes two
3248 parameters. The first is a string, the second is the name of a variable
3249 of the type designated by the attribute prefix. The first (string)
3250 argument is required to be a static expression and designates the
3251 constraint for the parameter (e.g.@: what kind of register is
3252 required). The second argument is the variable to be updated with the
3253 result. The possible values for constraint are the same as those used in
3254 the RTL, and are dependent on the configuration file used to build the
3255 GCC back end. If there are no output operands, then this argument may
3256 either be omitted, or explicitly given as @code{No_Output_Operands}.
3257 @ref{Machine Code Insertions}
3263 This attribute is implemented only in OpenVMS versions of GNAT@. Applied to
3264 the name of an entry, it yields a value of the predefined type AST_Handler
3265 (declared in the predefined package System, as extended by the use of
3266 pragma @code{Extend_System (Aux_DEC)}). This value enables the given entry to
3267 be called when an AST occurs. For further details, refer to the @cite{DEC Ada
3268 Language Reference Manual}, section 9.12a.
3272 @code{@var{obj}'Bit}, where @var{obj} is any object, yields the bit
3273 offset within the storage unit (byte) that contains the first bit of
3274 storage allocated for the object. The value of this attribute is of the
3275 type @code{Universal_Integer}, and is always a non-negative number not
3276 exceeding the value of @code{System.Storage_Unit}.
3278 For an object that is a variable or a constant allocated in a register,
3279 the value is zero. (The use of this attribute does not force the
3280 allocation of a variable to memory).
3282 For an object that is a formal parameter, this attribute applies
3283 to either the matching actual parameter or to a copy of the
3284 matching actual parameter.
3286 For an access object the value is zero. Note that
3287 @code{@var{obj}.all'Bit} is subject to an @code{Access_Check} for the
3288 designated object. Similarly for a record component
3289 @code{@var{X}.@var{C}'Bit} is subject to a discriminant check and
3290 @code{@var{X}(@var{I}).Bit} and @code{@var{X}(@var{I1}..@var{I2})'Bit}
3291 are subject to index checks.
3293 This attribute is designed to be compatible with the DEC Ada 83 definition
3294 and implementation of the @code{Bit} attribute.
3296 @findex Bit_Position
3299 @code{@var{R.C}'Bit}, where @var{R} is a record object and C is one
3300 of the fields of the record type, yields the bit
3301 offset within the record contains the first bit of
3302 storage allocated for the object. The value of this attribute is of the
3303 type @code{Universal_Integer}. The value depends only on the field
3304 @var{C} and is independent of the alignment of
3305 the containing record @var{R}.
3307 @findex Code_Address
3308 @cindex Subprogram address
3309 @cindex Address of subprogram code
3313 attribute may be applied to subprograms in Ada 95, but the
3314 intended effect from the Ada 95 reference manual seems to be to provide
3315 an address value which can be used to call the subprogram by means of
3316 an address clause as in the following example:
3319 procedure K is @dots{}
3322 for L'Address use K'Address;
3323 pragma Import (Ada, L);
3327 A call to @code{L} is then expected to result in a call to @code{K}@. In Ada 83, where
3328 there were no access-to-subprogram values, this was a common work around
3329 for getting the effect of an indirect call.
3330 GNAT implements the above use of @code{Address} and the technique illustrated
3331 by the example code works correctly.
3333 However, for some purposes, it is useful to have the address of the start
3334 of the generated code for the subprogram. On some architectures, this is
3335 not necessarily the same as the @code{Address} value described above. For example,
3336 the @code{Address} value may reference a subprogram descriptor rather than the
3339 The @code{'Code_Address} attribute, which can only be applied to
3340 subprogram entities, always returns the address of the start of the
3341 generated code of the specified subprogram, which may or may not be
3342 the same value as is returned by the corresponding @code{'Address}
3346 @cindex Little endian
3347 @findex Default_Bit_Order
3348 @item Default_Bit_Order
3350 @code{Standard'Default_Bit_Order} (@code{Standard} is the only
3351 permissible prefix), provides the value @code{System.Default_Bit_Order}
3352 as a @code{Pos} value (0 for @code{High_Order_First}, 1 for
3353 @code{Low_Order_First}). This is used to construct the definition of
3354 @code{Default_Bit_Order} in package @code{System}.
3359 The prefix of the @code{'Elaborated} attribute must be a unit name. The
3360 value is a Boolean which indicates whether or not the given unit has been
3361 elaborated. This attribute is primarily intended for internal use by the
3362 generated code for dynamic elaboration checking, but it can also be used
3363 in user programs. The value will always be True once elaboration of all
3364 units has been completed.
3369 This attribute can only be applied to a program unit name. It returns
3370 the entity for the corresponding elaboration procedure for elaborating
3371 the body of the referenced unit. This is used in the main generated
3372 elaboration procedure by the binder and is not normally used in any
3373 other context. However, there may be specialized situations in which it
3374 is useful to be able to call this elaboration procedure from Ada code,
3375 e.g.@: if it is necessary to do selective re-elaboration to fix some
3381 This attribute can only be applied to a program unit name. It returns
3382 the entity for the corresponding elaboration procedure for elaborating
3383 the specification of the referenced unit. This is used in the main
3384 generated elaboration procedure by the binder and is not normally used
3385 in any other context. However, there may be specialized situations in
3386 which it is useful to be able to call this elaboration procedure from
3387 Ada code, e.g.@: if it is necessary to do selective re-elaboration to fix
3390 @cindex Ada 83 attributes
3394 The @code{Emax} attribute is provided for compatibility with Ada 83. See
3395 the Ada 83 reference manual for an exact description of the semantics of
3398 @cindex Representation of enums
3402 For every enumeration subtype @var{S}, @code{@var{S}'Enum_Rep} denotes a
3403 function with the following specification:
3406 function @var{S}'Enum_Rep (Arg : @var{S}'Base)
3407 return Universal_Integer;
3411 It is also allowable to apply @code{Enum_Rep} directly to an object of an
3412 enumeration type or to a non-overloaded enumeration
3413 literal. In this case @code{@var{S}'Enum_Rep} is equivalent to
3414 @code{@var{typ}'Enum_Rep(@var{S})} where @var{typ} is the type of the
3415 enumeration literal or object.
3417 The function returns the representation value for the given enumeration
3418 value. This will be equal to value of the @code{Pos} attribute in the
3419 absence of an enumeration representation clause. This is a static
3420 attribute (i.e.@: the result is static if the argument is static).
3422 @code{@var{S}'Enum_Rep} can also be used with integer types and objects, in which
3423 case it simply returns the integer value. The reason for this is to allow
3424 it to be used for @code{(<>)} discrete formal arguments in a generic unit that
3425 can be instantiated with either enumeration types or integer types. Note
3426 that if @code{Enum_Rep} is used on a modular type whose upper bound exceeds the
3427 upper bound of the largest signed integer type, and the argument is a
3428 variable, so that the universal integer calculation is done at run-time,
3429 then the call to @code{Enum_Rep} may raise @code{Constraint_Error}.
3431 @cindex Ada 83 attributes
3435 The @code{Epsilon} attribute is provided for compatibility with Ada 83. See
3436 the Ada 83 reference manual for an exact description of the semantics of
3442 For every fixed-point type @var{S}, @code{@var{S}'Fixed_Value} denotes a
3443 function with the following specification:
3446 function @var{S}'Fixed_Value (Arg : Universal_Integer)
3451 The value returned is the fixed-point value @var{V} such that
3454 @var{V} = Arg * @var{S}'Small
3458 The effect is thus equivalent to first converting the argument to the
3459 integer type used to represent @var{S}, and then doing an unchecked
3460 conversion to the fixed-point type. This attribute is primarily intended
3461 for use in implementation of the input-output functions for fixed-point
3464 @cindex Discriminants, testing for
3465 @findex Has_Discriminants
3466 @item Has_Discriminants
3468 The prefix of the @code{Has_Discriminants} attribute is a type. The result
3469 is a Boolean value which is True if the type has discriminants, and False
3470 otherwise. The intended use of this attribute is in conjunction with generic
3471 definitions. If the attribute is applied to a generic private type, it
3472 indicates whether or not the corresponding actual type has discriminants.
3477 The @code{Img} attribute differs from @code{Image} in that it may be
3478 applied to objects as well as types, in which case it gives the
3479 @code{Image} for the subtype of the object. This is convenient for
3483 Put_Line ("X = " & X'Img);
3487 has the same meaning as the more verbose:
3490 Put_Line ("X = " & @var{type}'Image (X));
3493 where @var{type} is the subtype of the object X@.
3495 @findex Integer_Value
3498 For every integer type @var{S}, @code{@var{S}'Integer_Value} denotes a
3499 function with the following specification:
3502 function @var{S}'Integer_Value (Arg : Universal_Fixed)
3507 The value returned is the integer value @var{V}, such that
3510 Arg = @var{V} * @var{type}'Small
3514 The effect is thus equivalent to first doing an unchecked convert from
3515 the fixed-point type to its corresponding implementation type, and then
3516 converting the result to the target integer type. This attribute is
3517 primarily intended for use in implementation of the standard
3518 input-output functions for fixed-point values.
3520 @cindex Ada 83 attributes
3524 The @code{Large} attribute is provided for compatibility with Ada 83. See
3525 the Ada 83 reference manual for an exact description of the semantics of
3528 @findex Machine_Size
3531 This attribute is identical to the @code{Object_Size} attribute. It is
3532 provided for compatibility with the DEC Ada 83 attribute of this name.
3534 @cindex Ada 83 attributes
3538 The @code{Mantissa} attribute is provided for compatibility with Ada 83. See
3539 the Ada 83 reference manual for an exact description of the semantics of
3542 @cindex Interrupt priority, maximum
3543 @findex Max_Interrupt_Priority
3544 @item Max_Interrupt_Priority
3546 @code{Standard'Max_Interrupt_Priority} (@code{Standard} is the only
3547 permissible prefix), provides the value
3548 @code{System.Max_Interrupt_Priority} and is intended primarily for
3549 constructing this definition in package @code{System}.
3551 @cindex Priority, maximum
3552 @findex Max_Priority
3555 @code{Standard'Max_Priority} (@code{Standard} is the only permissible
3556 prefix) provides the value @code{System.Max_Priority} and is intended
3557 primarily for constructing this definition in package @code{System}.
3559 @cindex Alignment, maximum
3560 @findex Maximum_Alignment
3561 @item Maximum_Alignment
3563 @code{Standard'Maximum_Alignment} (@code{Standard} is the only
3564 permissible prefix) provides the maximum useful alignment value for the
3565 target. This is a static value that can be used to specify the alignment
3566 for an object, guaranteeing that it is properly aligned in all
3567 cases. This is useful when an external object is imported and its
3568 alignment requirements are unknown.
3570 @cindex Return values, passing mechanism
3571 @cindex Parameters, passing mechanism
3572 @findex Mechanism_Code
3573 @item Mechanism_Code
3575 @code{@var{function}'Mechanism_Code} yields an integer code for the
3576 mechanism used for the result of function, and
3577 @code{@var{subprogram}'Mechanism_Code (@var{n})} yields the mechanism
3578 used for formal parameter number @var{n} (a static integer value with 1
3579 meaning the first parameter) of @var{subprogram}. The code returned is:
3587 by descriptor (default descriptor class)
3589 by descriptor (UBS: unaligned bit string)
3591 by descriptor (UBSB: aligned bit string with arbitrary bounds)
3593 by descriptor (UBA: unaligned bit array)
3595 by descriptor (S: string, also scalar access type parameter)
3597 by descriptor (SB: string with arbitrary bounds)
3599 by descriptor (A: contiguous array)
3601 by descriptor (NCA: non-contiguous array)
3605 Values from 3 through 10 are only relevant to Digital OpenVMS implementations.
3607 @cindex Zero address, passing
3608 @findex Null_Parameter
3609 @item Null_Parameter
3611 A reference @code{@var{T}'Null_Parameter} denotes an imaginary object of
3612 type or subtype @var{T} allocated at machine address zero. The attribute
3613 is allowed only as the default expression of a formal parameter, or as
3614 an actual expression of a subprogram call. In either case, the
3615 subprogram must be imported.
3617 The identity of the object is represented by the address zero in the
3618 argument list, independent of the passing mechanism (explicit or
3621 This capability is needed to specify that a zero address should be
3622 passed for a record or other composite object passed by reference.
3623 There is no way of indicating this without the @code{Null_Parameter}
3626 @cindex Size, used for objects
3630 The size of an object is not necessarily the same as the size of the type
3631 of an object. This is because by default object sizes are increased to be
3632 a multiple of the alignment of the object. For example,
3633 @code{Natural'Size} is
3634 31, but by default objects of type @code{Natural} will have a size of 32 bits.
3635 Similarly, a record containing an integer and a character:
3645 will have a size of 40 (that is @code{Rec'Size} will be 40. The
3646 alignment will be 4, because of the
3647 integer field, and so the default size of record objects for this type
3648 will be 64 (8 bytes).
3650 The @code{@var{type}'Object_Size} attribute
3651 has been added to GNAT to allow the
3652 default object size of a type to be easily determined. For example,
3653 @code{Natural'Object_Size} is 32, and
3654 @code{Rec'Object_Size} (for the record type in the above example) will be
3655 64. Note also that, unlike the situation with the
3656 @code{Size} attribute as defined in the Ada RM, the
3657 @code{Object_Size} attribute can be specified individually
3658 for different subtypes. For example:
3661 type R is new Integer;
3662 subtype R1 is R range 1 .. 10;
3663 subtype R2 is R range 1 .. 10;
3664 for R2'Object_Size use 8;
3668 In this example, @code{R'Object_Size} and @code{R1'Object_Size} are both
3669 32 since the default object size for a subtype is the same as the object size
3670 for the parent subtype. This means that objects of type @code{R}
3672 by default be 32 bits (four bytes). But objects of type
3673 @code{R2} will be only
3674 8 bits (one byte), since @code{R2'Object_Size} has been set to 8.
3676 @cindex Parameters, when passed by reference
3677 @findex Passed_By_Reference
3678 @item Passed_By_Reference
3680 @code{@var{type}'Passed_By_Reference} for any subtype @var{type} returns
3681 a value of type @code{Boolean} value that is @code{True} if the type is
3682 normally passed by reference and @code{False} if the type is normally
3683 passed by copy in calls. For scalar types, the result is always @code{False}
3684 and is static. For non-scalar types, the result is non-static.
3686 @findex Range_Length
3689 @code{@var{type}'Range_Length} for any discrete type @var{type} yields
3690 the number of values represented by the subtype (zero for a null
3691 range). The result is static for static subtypes. @code{Range_Length}
3692 applied to the index subtype of a one dimensional array always gives the
3693 same result as @code{Range} applied to the array itself.
3695 @cindex Ada 83 attributes
3699 The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See
3700 the Ada 83 reference manual for an exact description of the semantics of
3703 @cindex Ada 83 attributes
3707 The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See
3708 the Ada 83 reference manual for an exact description of the semantics of
3711 @cindex Ada 83 attributes
3715 The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See
3716 the Ada 83 reference manual for an exact description of the semantics of
3719 @cindex Ada 83 attributes
3723 The @code{Small} attribute is defined in Ada 95 only for fixed-point types.
3724 GNAT also allows this attribute to be applied to floating-point types
3725 for compatibility with Ada 83. See
3726 the Ada 83 reference manual for an exact description of the semantics of
3727 this attribute when applied to floating-point types.
3729 @findex Storage_Unit
3732 @code{Standard'Storage_Unit} (@code{Standard} is the only permissible
3733 prefix) provides the value @code{System.Storage_Unit} and is intended
3734 primarily for constructing this definition in package @code{System}.
3739 @code{Standard'Tick} (@code{Standard} is the only permissible prefix)
3740 provides the value of @code{System.Tick} and is intended primarily for
3741 constructing this definition in package @code{System}.
3746 The @code{System'To_Address}
3747 (@code{System} is the only permissible prefix)
3748 denotes a function identical to
3749 @code{System.Storage_Elements.To_Address} except that
3750 it is a static attribute. This means that if its argument is
3751 a static expression, then the result of the attribute is a
3752 static expression. The result is that such an expression can be
3753 used in contexts (e.g.@: preelaborable packages) which require a
3754 static expression and where the function call could not be used
3755 (since the function call is always non-static, even if its
3756 argument is static).
3761 @code{@var{type}'Type_Class} for any type or subtype @var{type} yields
3762 the value of the type class for the full type of @var{type}. If
3763 @var{type} is a generic formal type, the value is the value for the
3764 corresponding actual subtype. The value of this attribute is of type
3765 @code{System.Aux_DEC.Type_Class}, which has the following definition:
3769 (Type_Class_Enumeration,
3771 Type_Class_Fixed_Point,
3772 Type_Class_Floating_Point,
3777 Type_Class_Address);
3781 Protected types yield the value @code{Type_Class_Task}, which thus
3782 applies to all concurrent types. This attribute is designed to
3783 be compatible with the DEC Ada 83 attribute of the same name.
3788 The @code{UET_Address} attribute can only be used for a prefix which
3789 denotes a library package. It yields the address of the unit exception
3790 table when zero cost exception handling is used. This attribute is
3791 intended only for use within the GNAT implementation. See the unit
3792 @code{Ada.Exceptions} in files @file{a-except.ads} and @file{a-except.adb}
3793 for details on how this attribute is used in the implementation.
3795 @cindex Named numbers, representation of
3796 @findex Universal_Literal_String
3797 @item Universal_Literal_String
3799 The prefix of @code{Universal_Literal_String} must be a named
3800 number. The static result is the string consisting of the characters of
3801 the number as defined in the original source. This allows the user
3802 program to access the actual text of named numbers without intermediate
3803 conversions and without the need to enclose the strings in quotes (which
3804 would preclude their use as numbers). This is used internally for the
3805 construction of values of the floating-point attributes from the file
3806 @file{ttypef.ads}, but may also be used by user programs.
3808 @cindex @code{Access}, unrestricted
3809 @findex Unrestricted_Access
3810 @item Unrestricted_Access
3812 The @code{Unrestricted_Access} attribute is similar to @code{Access}
3813 except that all accessibility and aliased view checks are omitted. This
3814 is a user-beware attribute. It is similar to
3815 @code{Address}, for which it is a desirable replacement where the value
3816 desired is an access type. In other words, its effect is identical to
3817 first applying the @code{Address} attribute and then doing an unchecked
3818 conversion to a desired access type. In GNAT, but not necessarily in
3819 other implementations, the use of static chains for inner level
3820 subprograms means that @code{Unrestricted_Access} applied to a
3821 subprogram yields a value that can be called as long as the subprogram
3822 is in scope (normal Ada 95 accessibility rules restrict this usage).
3824 @cindex @code{Size}, VADS compatibility
3828 The @code{'VADS_Size} attribute is intended to make it easier to port
3829 legacy code which relies on the semantics of @code{'Size} as implemented
3830 by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the
3831 same semantic interpretation. In particular, @code{'VADS_Size} applied
3832 to a predefined or other primitive type with no Size clause yields the
3833 Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on
3834 typical machines). In addition @code{'VADS_Size} applied to an object
3835 gives the result that would be obtained by applying the attribute to
3836 the corresponding type.
3838 @cindex @code{Size}, setting for not-first subtype
3841 @code{@var{type}'Value_Size} is the number of bits required to represent
3842 a value of the given subtype. It is the same as @code{@var{type}'Size},
3843 but, unlike @code{Size}, may be set for non-first subtypes.
3845 @findex Wchar_T_Size
3847 @code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible
3848 prefix) provides the size in bits of the C @code{wchar_t} type
3849 primarily for constructing the definition of this type in
3850 package @code{Interfaces.C}.
3854 @code{Standard'Word_Size} (@code{Standard} is the only permissible
3855 prefix) provides the value @code{System.Word_Size} and is intended
3856 primarily for constructing this definition in package @code{System}.
3858 @node Implementation Advice
3859 @chapter Implementation Advice
3860 The main text of the Ada 95 Reference Manual describes the required
3861 behavior of all Ada 95 compilers, and the GNAT compiler conforms to
3864 In addition, there are sections throughout the Ada 95
3865 reference manual headed
3866 by the phrase ``implementation advice''. These sections are not normative,
3867 i.e.@: they do not specify requirements that all compilers must
3868 follow. Rather they provide advice on generally desirable behavior. You
3869 may wonder why they are not requirements. The most typical answer is
3870 that they describe behavior that seems generally desirable, but cannot
3871 be provided on all systems, or which may be undesirable on some systems.
3873 As far as practical, GNAT follows the implementation advice sections in
3874 the Ada 95 Reference Manual. This chapter contains a table giving the
3875 reference manual section number, paragraph number and several keywords
3876 for each advice. Each entry consists of the text of the advice followed
3877 by the GNAT interpretation of this advice. Most often, this simply says
3878 ``followed'', which means that GNAT follows the advice. However, in a
3879 number of cases, GNAT deliberately deviates from this advice, in which
3880 case the text describes what GNAT does and why.
3883 @cindex Error detection
3884 @item 1.1.3(20): Error Detection
3887 If an implementation detects the use of an unsupported Specialized Needs
3888 Annex feature at run time, it should raise @code{Program_Error} if
3891 Not relevant. All specialized needs annex features are either supported,
3892 or diagnosed at compile time.
3895 @item 1.1.3(31): Child Units
3898 If an implementation wishes to provide implementation-defined
3899 extensions to the functionality of a language-defined library unit, it
3900 should normally do so by adding children to the library unit.
3904 @cindex Bounded errors
3905 @item 1.1.5(12): Bounded Errors
3908 If an implementation detects a bounded error or erroneous
3909 execution, it should raise @code{Program_Error}.
3911 Followed in all cases in which the implementation detects a bounded
3912 error or erroneous execution. Not all such situations are detected at
3916 @item 2.8(16): Pragmas
3919 Normally, implementation-defined pragmas should have no semantic effect
3920 for error-free programs; that is, if the implementation-defined pragmas
3921 are removed from a working program, the program should still be legal,
3922 and should still have the same semantics.
3924 The following implementation defined pragmas are exceptions to this
3936 @item CPP_Constructor
3944 @item Interface_Name
3946 @item Machine_Attribute
3948 @item Unimplemented_Unit
3950 @item Unchecked_Union
3954 In each of the above cases, it is essential to the purpose of the pragma
3955 that this advice not be followed. For details see the separate section
3956 on implementation defined pragmas.
3958 @item 2.8(17-19): Pragmas
3961 Normally, an implementation should not define pragmas that can
3962 make an illegal program legal, except as follows:
3966 A pragma used to complete a declaration, such as a pragma @code{Import};
3970 A pragma used to configure the environment by adding, removing, or
3971 replacing @code{library_items}.
3973 See response to paragraph 16 of this same section.
3975 @cindex Character Sets
3976 @cindex Alternative Character Sets
3977 @item 3.5.2(5): Alternative Character Sets
3980 If an implementation supports a mode with alternative interpretations
3981 for @code{Character} and @code{Wide_Character}, the set of graphic
3982 characters of @code{Character} should nevertheless remain a proper
3983 subset of the set of graphic characters of @code{Wide_Character}. Any
3984 character set ``localizations'' should be reflected in the results of
3985 the subprograms defined in the language-defined package
3986 @code{Characters.Handling} (see A.3) available in such a mode. In a mode with
3987 an alternative interpretation of @code{Character}, the implementation should
3988 also support a corresponding change in what is a legal
3989 @code{identifier_letter}.
3991 Not all wide character modes follow this advice, in particular the JIS
3992 and IEC modes reflect standard usage in Japan, and in these encoding,
3993 the upper half of the Latin-1 set is not part of the wide-character
3994 subset, since the most significant bit is used for wide character
3995 encoding. However, this only applies to the external forms. Internally
3996 there is no such restriction.
3998 @cindex Integer types
3999 @item 3.5.4(28): Integer Types
4003 An implementation should support @code{Long_Integer} in addition to
4004 @code{Integer} if the target machine supports 32-bit (or longer)
4005 arithmetic. No other named integer subtypes are recommended for package
4006 @code{Standard}. Instead, appropriate named integer subtypes should be
4007 provided in the library package @code{Interfaces} (see B.2).
4009 @code{Long_Integer} is supported. Other standard integer types are supported
4010 so this advice is not fully followed. These types
4011 are supported for convenient interface to C, and so that all hardware
4012 types of the machine are easily available.
4013 @item 3.5.4(29): Integer Types
4017 An implementation for a two's complement machine should support
4018 modular types with a binary modulus up to @code{System.Max_Int*2+2}. An
4019 implementation should support a non-binary modules up to @code{Integer'Last}.
4023 @cindex Enumeration values
4024 @item 3.5.5(8): Enumeration Values
4027 For the evaluation of a call on @code{@var{S}'Pos} for an enumeration
4028 subtype, if the value of the operand does not correspond to the internal
4029 code for any enumeration literal of its type (perhaps due to an
4030 un-initialized variable), then the implementation should raise
4031 @code{Program_Error}. This is particularly important for enumeration
4032 types with noncontiguous internal codes specified by an
4033 enumeration_representation_clause.
4038 @item 3.5.7(17): Float Types
4041 An implementation should support @code{Long_Float} in addition to
4042 @code{Float} if the target machine supports 11 or more digits of
4043 precision. No other named floating point subtypes are recommended for
4044 package @code{Standard}. Instead, appropriate named floating point subtypes
4045 should be provided in the library package @code{Interfaces} (see B.2).
4047 @code{Short_Float} and @code{Long_Long_Float} are also provided. The
4048 former provides improved compatibility with other implementations
4049 supporting this type. The latter corresponds to the highest precision
4050 floating-point type supported by the hardware. On most machines, this
4051 will be the same as @code{Long_Float}, but on some machines, it will
4052 correspond to the IEEE extended form. The notable case is all ia32
4053 (x86) implementations, where @code{Long_Long_Float} corresponds to
4054 the 80-bit extended precision format supported in hardware on this
4055 processor. Note that the 128-bit format on SPARC is not supported,
4056 since this is a software rather than a hardware format.
4058 @cindex Multidimensional arrays
4059 @cindex Arrays, multidimensional
4060 @item 3.6.2(11): Multidimensional Arrays
4063 An implementation should normally represent multidimensional arrays in
4064 row-major order, consistent with the notation used for multidimensional
4065 array aggregates (see 4.3.3). However, if a pragma @code{Convention}
4066 (@code{Fortran}, @dots{}) applies to a multidimensional array type, then
4067 column-major order should be used instead (see B.5, ``Interfacing with
4072 @findex Duration'Small
4073 @item 9.6(30-31): Duration'Small
4076 Whenever possible in an implementation, the value of @code{Duration'Small}
4077 should be no greater than 100 microseconds.
4079 Followed. (@code{Duration'Small} = 10**(@minus{}9)).
4083 The time base for @code{delay_relative_statements} should be monotonic;
4084 it need not be the same time base as used for @code{Calendar.Clock}.
4088 @item 10.2.1(12): Consistent Representation
4091 In an implementation, a type declared in a pre-elaborated package should
4092 have the same representation in every elaboration of a given version of
4093 the package, whether the elaborations occur in distinct executions of
4094 the same program, or in executions of distinct programs or partitions
4095 that include the given version.
4097 Followed, except in the case of tagged types. Tagged types involve
4098 implicit pointers to a local copy of a dispatch table, and these pointers
4099 have representations which thus depend on a particular elaboration of the
4100 package. It is not easy to see how it would be possible to follow this
4101 advice without severely impacting efficiency of execution.
4103 @cindex Exception information
4104 @item 11.4.1(19): Exception Information
4107 @code{Exception_Message} by default and @code{Exception_Information}
4108 should produce information useful for
4109 debugging. @code{Exception_Message} should be short, about one
4110 line. @code{Exception_Information} can be long. @code{Exception_Message}
4111 should not include the
4112 @code{Exception_Name}. @code{Exception_Information} should include both
4113 the @code{Exception_Name} and the @code{Exception_Message}.
4115 Followed. For each exception that doesn't have a specified
4116 @code{Exception_Message}, the compiler generates one containing the location
4117 of the raise statement. This location has the form ``file:line'', where
4118 file is the short file name (without path information) and line is the line
4119 number in the file. Note that in the case of the Zero Cost Exception
4120 mechanism, these messages become redundant with the Exception_Information that
4121 contains a full backtrace of the calling sequence, so they are disabled.
4122 To disable explicitly the generation of the source location message, use the
4123 Pragma @code{Discard_Names}.
4125 @cindex Suppression of checks
4126 @cindex Checks, suppression of
4127 @item 11.5(28): Suppression of Checks
4130 The implementation should minimize the code executed for checks that
4131 have been suppressed.
4135 @cindex Representation clauses
4136 @item 13.1 (21-24): Representation Clauses
4139 The recommended level of support for all representation items is
4140 qualified as follows:
4144 An implementation need not support representation items containing
4145 non-static expressions, except that an implementation should support a
4146 representation item for a given entity if each non-static expression in
4147 the representation item is a name that statically denotes a constant
4148 declared before the entity.
4150 Followed. GNAT does not support non-static expressions in representation
4151 clauses unless they are constants declared before the entity. For
4156 for X'Address use To_address (16#2000#);
4160 will be rejected, since the To_Address expression is non-static. Instead
4164 X_Address : constant Address : =
4165 To_Address ((16#2000#);
4167 for X'Address use X_Address;
4172 An implementation need not support a specification for the @code{Size}
4173 for a given composite subtype, nor the size or storage place for an
4174 object (including a component) of a given composite subtype, unless the
4175 constraints on the subtype and its composite subcomponents (if any) are
4176 all static constraints.
4178 Followed. Size Clauses are not permitted on non-static components, as
4183 An aliased component, or a component whose type is by-reference, should
4184 always be allocated at an addressable location.
4188 @cindex Packed types
4189 @item 13.2(6-8): Packed Types
4192 If a type is packed, then the implementation should try to minimize
4193 storage allocated to objects of the type, possibly at the expense of
4194 speed of accessing components, subject to reasonable complexity in
4195 addressing calculations.
4199 The recommended level of support pragma @code{Pack} is:
4201 For a packed record type, the components should be packed as tightly as
4202 possible subject to the Sizes of the component subtypes, and subject to
4203 any @code{record_representation_clause} that applies to the type; the
4204 implementation may, but need not, reorder components or cross aligned
4205 word boundaries to improve the packing. A component whose @code{Size} is
4206 greater than the word size may be allocated an integral number of words.
4208 Followed. Tight packing of arrays is supported for all component sizes
4213 An implementation should support Address clauses for imported
4217 @cindex @code{Address} clauses
4218 @item 13.3(14-19): Address Clauses
4222 For an array @var{X}, @code{@var{X}'Address} should point at the first
4223 component of the array, and not at the array bounds.
4229 The recommended level of support for the @code{Address} attribute is:
4231 @code{@var{X}'Address} should produce a useful result if @var{X} is an
4232 object that is aliased or of a by-reference type, or is an entity whose
4233 @code{Address} has been specified.
4235 Followed. A valid address will be produced even if none of those
4236 conditions have been met. If necessary, the object is forced into
4237 memory to ensure the address is valid.
4241 An implementation should support @code{Address} clauses for imported
4248 Objects (including subcomponents) that are aliased or of a by-reference
4249 type should be allocated on storage element boundaries.
4255 If the @code{Address} of an object is specified, or it is imported or exported,
4256 then the implementation should not perform optimizations based on
4257 assumptions of no aliases.
4261 @cindex @code{Alignment} clauses
4262 @item 13.3(29-35): Alignment Clauses
4265 The recommended level of support for the @code{Alignment} attribute for
4268 An implementation should support specified Alignments that are factors
4269 and multiples of the number of storage elements per word, subject to the
4276 An implementation need not support specified @code{Alignment}s for
4277 combinations of @code{Size}s and @code{Alignment}s that cannot be easily
4278 loaded and stored by available machine instructions.
4284 An implementation need not support specified @code{Alignment}s that are
4285 greater than the maximum @code{Alignment} the implementation ever returns by
4292 The recommended level of support for the @code{Alignment} attribute for
4295 Same as above, for subtypes, but in addition:
4301 For stand-alone library-level objects of statically constrained
4302 subtypes, the implementation should support all @code{Alignment}s
4303 supported by the target linker. For example, page alignment is likely to
4304 be supported for such objects, but not for subtypes.
4308 @cindex @code{Size} clauses
4309 @item 13.3(42-43): Size Clauses
4312 The recommended level of support for the @code{Size} attribute of
4315 A @code{Size} clause should be supported for an object if the specified
4316 @code{Size} is at least as large as its subtype's @code{Size}, and
4317 corresponds to a size in storage elements that is a multiple of the
4318 object's @code{Alignment} (if the @code{Alignment} is nonzero).
4322 @item 13.3(50-56): Size Clauses
4325 If the @code{Size} of a subtype is specified, and allows for efficient
4326 independent addressability (see 9.10) on the target architecture, then
4327 the @code{Size} of the following objects of the subtype should equal the
4328 @code{Size} of the subtype:
4330 Aliased objects (including components).
4336 @code{Size} clause on a composite subtype should not affect the
4337 internal layout of components.
4343 The recommended level of support for the @code{Size} attribute of subtypes is:
4347 The @code{Size} (if not specified) of a static discrete or fixed point
4348 subtype should be the number of bits needed to represent each value
4349 belonging to the subtype using an unbiased representation, leaving space
4350 for a sign bit only if the subtype contains negative values. If such a
4351 subtype is a first subtype, then an implementation should support a
4352 specified @code{Size} for it that reflects this representation.
4358 For a subtype implemented with levels of indirection, the @code{Size}
4359 should include the size of the pointers, but not the size of what they
4364 @cindex @code{Component_Size} clauses
4365 @item 13.3(71-73): Component Size Clauses
OSDN Git Service
