GNAT IMPLEMENTED FEATURES LIST Current as of 08/17/96 Here is the list of implemented and not implemented features, including a full description of implementation-defined pragmas and attributes. For information on how to use GNAT, see gnatinfo.txt. Latest features in GNAT version 3.07 ==================================== GNAT now checks for the case of a body file present when the spec does not require a body. GNAT always diagnosed the error when the body was compiled, but if only the spec was compiled, the suspicious body was ignored. The presence of a body file when no body is allowed is now considered an error in Ada 95 mode, and a warning in Ada 83 mode. Packed arrays with bounds depending on a discriminant now work correctly The DEC pragmas have been implemented. Those of interest to GNAT ports in general are as follows (see below for full documentation) Common_Object Component_Alignment Export_Function Export_Object Export_Procedure Export_Valued_Procedure Import_Function Import_Object Import_Procedure Import_Valued_Procedure Suppress_All The DEC attributes have been implemented. Those of interest to GNAT ports in general are as follows (see below for full documentation) Bit Machine_Size Null_Parameter Type_Class Attribute Mechanism_Code allows determination of the parameter passing mechanism chosen by GNAT, as possibly controlled by the Import, Export and C_Pass_By_Copy pragmas. Pragma Extend_System allows transparent extension of package System to accomodate definitions from other implementations of Ada. Machine code insertions have been completely implemented. A new section in gnatinfo.txt describes the use. Both code statements as such, and also intrinsic calls are available. The latter allow interspersing machine instructions in Ada code. Inlining of machine code procedures is fully supported. The pragma C_Pass_By_Copy is implemented in a manner that is completely compatible with the Intermetrics implementation of this pragma. The default mechanism for passing records to foreign convention subprograms is now by-reference. This can be modified by either use of one of the DEC extended Import/Export pragmas, or by use of the C_Pass_By_Copy pragma. Further extended support for representation clauses, including more cases of misaligned fields, and non-standard layouts. Record representation clauses no longer require that the position of all fields be specified. Pragma Error_Monitoring has been removed. This pragma was not used and had a number of conceptual and implementation problems. Latest features in GNAT version 3.06 ==================================== This version is available only from SGI, and is an intermediate version between the ACT 3.05 and 3.07 releases. Consult SGI for further details Latest features in GNAT version 3.05 ==================================== Implement tight array packing for component sizes up to 31 bits Relaxation of alignment and size rules allow more record rep clauses to be accepted and correctly processed. ACVC compliance for SGI matches that of the official validation Latest features in GNAT version 3.04 ==================================== GNAT attributes mantissa, safe_small for fixed points GNAT attribute small for floating point These attributes correspond to attributes defined in Ada 83. gnatlink (new utility program) pragma Unchecked_Union is fully implemented (see end of this document) More efficient execution of programs containing exception handlers (especially on Sun Sparc) Many new options to gnatmake: (see gnatinfo.txt for details) -aI -aO, -jnum, -k, -l, -o New Source & Library search path switches: (see gnatinfo.txt for details) -aLdir, -Adir, -aOdir, -aIdir, -Idir, -I-, -Ldir The DOS version has been migrated to DJGPP v2. Tasking is now fully functional in the DOS version. "Real" memory problems in the DOS version have been alleviated. New warnings for some infinite recursion cases When an Assert_Failure exception is raised, the exception is raised with a message, either the file name and line number by default of the pragma Assert, or the string explicitly supplied as the second parameter. The restriction names No_GNAT_Attributes and No_GNAT_Pragmas have been renamed No_Implementation_Attributes and No_Implementation_Pragmas. Record Representation Clauses which do not specify representations for all components (partial rep clauses) are now accepted by GNAT. Packed arrays of records are now implemented. The Size attribute is now handled as specified in the RM. This means that the value of 'Size will often be different from what it was before and what it was in Ada 83. Two new attributes Object_Size and Value_Size have been added to provide additional control. Latest features in GNAT version 3.03 ==================================== Implement packing of multidimensional arrays Get_Immediate now follows the implementation advice and works as intended (for SGI IRIX, Sparc SunOS/Solaris, Alpha OSF1, IBM OS/2 and Linux) The task attributes package is now fully functional Warnings for unset variables, and possible access before initialization pragma Warnings (On | Off) allows more detailed control of warnings pragma Source_File_Name allows specifying non-standard file names pragma No_Return allows specifying a procedure that never returns pragma Attach_Handler (implemented on Sparc SunOS and Sparc Solaris only) pragma Interrupt_Handler (implemented on Sparc SunOS and Sparc Solaris only) Latest features in GNAT version 3.01 ==================================== pragma Normalize_Scalars Ada.Text_IO.Editing Ada.Wide_Text_IO.Editing Incomplete types declared in the private part that are completed in the package body as unconstrained arrays. Full implementation of stream attributes, including the dispatching cases for class wide types. Private protected operations Pointers to unconstrained arrays may be double or single length. Double ("fat") is the default size (e.g. 64 on SGI), but rep clauses or a foreign convention will force them to single length. Aggregates for composite Types with controlled components Objects of type with unknown discriminants pragma Queuing_Policy pragma Source_File_Name (GNAT specific) True multiprocessing on Sparc Solaris Latest features in GNAT version 2.07 ==================================== Discriminant checks Package Ada.Exceptions External_Tag attribute Identity attribute Range Checks on the elaboration of a subtype_indication Duration is an ordinary fixed-point type with delta of one nanosecond Package Interfaces.COBOL Protected subprogram pointers Caller attribute Restriction pragma All restrictions in real time annex All restrictions in safety and security annex Higher resolution clocks for tasking on SunOS/Solaris Latest features in GNAT version 2.06 ==================================== Requeue Statement involving task entries inter-unit inlining (enabled by -O2 -gnatn) aggregates for simple controlled types Latest features in GNAT version 2.05 ==================================== Elaboration Checks A new switch -gnati8 specifies the use of IBM PC Code Page 850 for the identifier character set (this is Latin-1 a la IBM PC) Protected entry families Ada.Synchronous_Task_Control Attribute Storage_Pool Packed arrays (including packed boolean arrays) Accessibility checks -I for specifying source and object path (see gnatinfo.txt for details) Conditional protected entry calls Delay until inside select statements Latest features in GNAT version 2.04 ==================================== GNATMAKE utility (see gnatinfo.txt for details) Pragma Export Ada.Streams.Stream_IO Attribute Definite Interrupt entries Input-Output for Modular Types Input-Output for Decimal Types Input-Output for Integer for type Long_Long_Integer. The following are now implemented in package Ada.Text_IO Flush Look_Ahead Get_Immediate Text_IO.Complex_IO Text_IO.Text_Streams Wide_Text_IO Wide_Text_IO.Complex_IO Wide_Text_IO.Text_Streams Note: All the I/O packages have been rewritten from the ground up for this release, and should completely implement all features of the RM. To get file sharing, allowed only if the files are for the same I/O package and same mode, use a form parameter shared=yes. Status of Features This list applies to the ports for the following targets: SGI (IRIX 5.3) Sun Sparc (SunOS 4.1 and Solaris 2.3), x86 (DOS, IBM OS/2, Linux, NetBSD, Windows 95, Windows NT) DEC Alpha (Digital Unix) HP (HPUX) Power Mac (Machten) Other targets are generally complete except that no tasking constructs are implemented. ========================================================== = All of Ada 83 is implemented EXCEPT for the following: = ========================================================== Stack overflow checking is implemented only on the SGI machines ========================================================================= = All of Ada 95 implemented EXCEPT the following unimplemented features = ========================================================================= CORE (fully implemented) ANNEX A. PREDEFINED LANGUAGE ENVIRONMENT Ada.Interrupts (implemented on Sparc SunOS and Sparc Solaris only) ANNEX B. INTERFACING TO OTHER LANGUAGES (fully implemented) ANNEX C. SYSTEMS PROGRAMMING Interrupt support (implemented on Sparc SunOS and Sparc Solaris only) Ada.Interrupts (implemented on Sparc SunOS and Sparc Solaris only) ANNEX D. REAL-TIME SYSTEMS (fully implemented) ANNEX E. DISTRIBUTED SYSTEMS (fully implemented) (this refers to the compiler part, stub generation and the pragmas) ANNEX F. INFORMATION SYSTEMS (fully implemented) ANNEX G. NUMERICS (fully implemented) ANNEX H. SAFETY AND SECURITY (fully implemented) ANNEX I. OBSOLESCENT FEATURES (fully implemented) ANNEX J. LANGUAGE-DEFINED ATTRIBUTES (fully implemented) ANNEX K. LANGUAGE DEFINED PRAGMAS Attach_Handler (implemented on Sparc SunOS and Sparc Solaris only) Interrupt_Handler (implemented on Sparc SunOS and Sparc Solaris only) ================================ = Description of GNAT Pragmas == ================================ pragma Abort_Defer; This pragma is implementation (GNAT) defined. It must appear at the start of the statement sequence of a handled sequence of statements (right after the begin). It has the effect of deferring aborts for the sequence of statements (but not for the declarations or handlers, if any, associated with this statement sequence). The exception case is handled correctly, i.e. if the statement sequence propagates an exception, then abort is properly undeferred. pragma Ada_83; This pragma is implementation (GNAT) defined. It establishes Ada 83 mode for following text, regardless of the mode set by the command line switches. Note that this is not a configuration pragma, so it must be given separately for each unit to which it applies. pragma Ada_95; This pragma is implementation (GNAT) defined. It establishes Ada 95 mode for following text, regardless of the mode set by the command line switches. Note that this is not a configuration pragma, so it must be given separately for each unit to which it applies. Note: Ada 95 mode is set automatically for predefined language units, including children of GNAT, so need not be given for any such units. pragma Annotate (IDENTIFIER {, ARG}); ARG ::= NAME | EXPRESSION This pragma is an implementation (GNAT) defined pragma used to annotate programs. The first argument is simply an identifier that identifies the type of annotation. GNAT verifies that this is an identifier, but does not otherwise analyze it. The arguments following this identifier are analyzed as follows: String literals are assumed to be of type Standard.String Names of entities are simply analyzed as entity names All other expressions are analyzed as expressions, and must be unambiguous The analyzed pragma is retained in the tree, but not otherwise processed by any part of the GNAT compiler. This pragma is intended for use by external tools. pragma Assert (Boolean_EXPRESSION [,static_string_EXPRESSION]); This pragma is implementation (GNAT) defined. Its effect depends on whether the corresponding command line switch is set to activate assertions. If assertions are inactive, the pragma has no effect. If asserts are enabled, then the semantics of the pragma is exactly equivalent to: if not Boolean_EXPRESSION then System.Assertions.Raise_Assert_Failure (string_EXPRESSION); end if; The effect of the call is to raise System.Assertions.Assert_Failure. The string argument, if given, is the message associated with the exception occurrence. If no second argument is given, the default message is "file:nnn", where file is the name of the source file containing the assert, and nnn is the line number of the assert. Note: a pragma is not a statement, so if a statement sequence contains nothing but a pragma assert, then a null statement is required in addition, as in: ... if J > 3 then pragma (Assert (K > 3, "Bad value for K")); null; end if; Note: if the boolean expression has side effects, then these side effects will turn on and off with the setting of the assertions mode, resulting in assertions that have an effect on the program. This should generally be avoided. pragma C_Pass_By_Copy ([Max_Size =>] static_integer_EXPRESSION); Normally the default mechanism for passing C convention records to C convention subprograms is to pass them by reference, as suggested by RM B.3(69). The configuration pragma C_Pass_By_Copy can be used to change this default, by requiring that record formal parameters be passed by copy if the following conditions are met: The size of the record type does not exceed the argument value given in the C_Pass_By_Copy pragma. The record type has convention C The formal parameter has this record type, and the subprogram has a foreign (non-Ada) convention. If these conditions are met, then the argument is passed by copy, i.e. in a manner consistent with what C expects if the corresponding formal in the C prototype is a struct (rather than a pointer to a struct). Note: pass by copy of records can also be achieved by specifying the convention C_Pass_By_Copy for the record type, or by the use of the extended Import and Export pragmas that allow specification of passing mechanisms on a parameter by parameter basis. pragma CPP_Class ([Entity =>] LOCAL_NAME) The argument denotes an entity in the current declarative region that is declared as a tagged or untagged record type. It indicates that the type corresponds to an externally declared C++ class type, and is to be layed out the same way that C++ would lay out the type. If (and only if) the type is tagged, at least one component in the record must be of type Interfaces.CPP.Vtable_Ptr, corresponding to the C++ Vtable (or Vtables in the case of multiple inheritance) used for dispatching. Types for which CPP_Class is defined do not have assignment or equality operators defined (such operations can be imported or declared as subprograms as required). Initialization is allowed only by constructor functions (see pragma CPP_Constructor). pragma Common_Object [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Size =>] EXTERNAL_SYMBOL] This pragma enables the shared use of variables that are stored in overlaid linker areas corresponding to the use of COMMON in Fortran. A single object is assigned to the area designated by the given external symbol. Note that a record can be defined to correspond to a series of fields. The Size field is syntax checked in GNAT, but otherwise ignored. pragma Component_Alignment ( [Form =>] ALIGNMENT_CHOICE [, [Name =>] type_LOCAL_NAME]); ALIGNMENT_CHOICE ::= Component_Size | Component_Size_4 | Storage_Unit | Default This pragma is compatible with DEC pragma of the same name, and is used to allow the specification of a default storage representation for declarative parts or array or record types. It can also be used in GNAT as a configuration pragma to apply to an entire environment. The alignment choices are as follows Component_Size Specifies that scalar components and subcomponents of the array or record type are aligned on boundaries appropriate to their inherent size (naturally aligned). For example, 1-byte components are aligned on byte boundaries, 2-byte integer components are aligned on 2-byte boundaries, 4-byte integer components are aligned on 4-byte boundaries and so on. These alignment rules correspond to the normal rules for C compilers on all machines except the VAX. Component_Size_4 Specifies that components with a size of four or fewer bytes are naturally aligned. Components that are larger than 4 bytes are placed on the next 4-byte boundary. Storage_Unit Specifies that array or record components are byte aligned, i.e. aligned on boundaries determined by the value of the constant System.Storage_Unit. Default Specifies that array or record components are aligned on default boundaries, appropriate to the nderlying hardware or operating system or both. For OpenVMS VAX systems, the effect of the Default choice is the same as the Storage_Unit choice (byte alignment). For all other systems, the effect of the Default choice is the same as Component_Size (Natural alignment). If the Name parameter is present, it must refer to a local record or array type, and the specified alignment choice applies to the specified type. The use of Component_Alignment together with Pack causes the Component_Alignment pragma to be ignored. The use of Component_Alignment together with a record representation clause is only effective for fields not specified by the representation clause. If the Name parameter is absent, then the pragma can be used as either a configuration pragma, in which case it applies to one or more units in accordance with the normal rules for configuration pragmas, or it can be used within a declarative part, in which case it applies to types that are declared within this declarative part, or within any nested scope within this declarative part. In either case it specifies the alignment to be applied to any record or array type which has otherwise standard representation. Note: if the alignment for a record or array type is not specified (using pragma Pack, pragma Component_Alignment, or a record rep clause), then the default alignment is applied as described above. pragma CPP_Constructor ([Entity =>] LOCAL_NAME); This pragma identifies an imported function (imported in the usual way with pragma Import) as corresponding to a C++ constructor. The identified function must be previously mentioned in a pragma Import with convention C++, and must be of one of the following forms: function Fname return T'Class; function Fname () return T'Class; where T is a tagged type to which the pragma CPP_Class applies. The first form is the default constructor, used when an object of type T is created on the Ada side with no explicit constructor. Other constructors (including the copy constructor, which is simply a special case of the second form in which the one and only argument is of type T), can only appear in two contexts: On the right side of an initialization of an object of type T In an extension aggregate for an object of a type derived from T Note that although the constructor is described as a function that returns a value on the Ada side, it is typically a procedure with an extra implicit argument (the object being initialized) at the implementation level. GNAT takes care of issuing the appropriate call, whatever it is, to get the object properly initialized. Note: in the case of derived objects, there are two possible forms for declaring and creating an object: New_Object : Derived_T; New_Object : Derived_T := (constructor-function-call with ...); In the first case the default constructor is called, and extension fields if any are initialized according to the default initialization expressions in the Ada declaration. In the second case, the given constructor is called, and the extension aggregate indicates the explicit values of the extension fields. Note: if no constructors are imported then it is impossible to create any objects on the Ada side. If no default constructor is imported, then only the initialization forms using an explicit call to a constructor are permitted. pragma CPP_Destructor ([Entity =>] LOCAL_NAME); This pragma identifies an imported procedure (imported in the usual way with pragma Import) as corresponding to a C++ destructor. The identified procedure must be previously mentioned in a pragma Import with convention C++, and must be of the following forms: procedure Fname (obj : in out T'Class); where T is a tagged type to which the pragma CPP_Class applies. This procedure will be called automaticlly on scope exit if any objects of T are created on the Ada side. pragma CPP_Virtual [Entity =>] LOCAL_NAME [ [Vtable_Ptr =>] Component_NAME, [Position =>] static_integer_EXPRESSION]); This pragma serves the same function as pragma Import for the case of a virtual function that is imported from C++. Entity must refer to a primitive subprogram of a tagged type to which pragma CPP_Class applies. Vtable_Ptr specifies the Vtable_Ptr component which contains the entry for this virtual function, and Position is the sequential number counting virtual functions for this Vtable starting at 1. The Vtable_Ptr and Position arguments may be omitted if there is one Vtable_Ptr present (single inheritance case), and all virtual functions are imported, since then the compiler can deduce both these values. Note that no External_Name or Link_Name arguments are required for a virtual function, since it is always accessed indirectly via the appropriate Vtable entry. pragma CPP_Vtable ( [Entity =>] LOCAL_NAME [Vtable_Ptr =>] Component_NAME, [Entry_Count =>] static_integer_EXPRESSION); One CPP_Vtable pragma can be present for each component of type CPP.Interfaces.Vtable_Ptr in a record to which pragma CPP_Class applies. Entity is the tagged type, Vtable_Ptr is the record field of type Vtable_Ptr, and Entry_Count is the number of virtual functions on the C++ side (not all of which need to be imported on the Ada side). It is permissible to omit the CPP_Vtable pragma if there is only one Vtable_Ptr component in the record, and all virtual functions are imported on the Ada side (the default value for the entry count in this case is simply the total number of virtual functions). pragma Debug (PROCEDURE_CALL_STATEMENT); This pragma is implementation (GNAT) defined. Its effect depends on the setting of the Assertions_Enabled flag in Opt. If this flag is off (False), then the pragma has no effect. If the flag is on (True), then the semantics of the pragma is equivalent to the procedure call. pragma Export_Function ( [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL,] [, [Parameter_Types =>] (PARAMETER_TYPES)] [, [Result_Type =>] SUBTYPE_MARK] [, [Mechanism =>] MECHANISM] [, [Result_Mechanism =>] MECHANISM_NAME]); PARAMETER_TYPES ::= null | SUBTYPE_MARK {, SUBTYPE_MARK} MECHANISM ::= MECHANISM_NAME | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) MECHANISM_ASSOCIATION ::= [formal_parameter_NAME =>] MECHANISM_NAME MECHANISM_NAME ::= Value | Reference | Descriptor [([Class =>] CLASS_NAME)] CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca This pragma is used to make a function externally callable, and to optinally provide information on mechanisms to be used for passing parameter and result values. It is recommended (for the purposes of improving portability) that this pragma always be used in conjunction with a separate pragma Export which must precede the pragma Export_Function. However, this is not required and if no separate pragma Export is present, then Convention C is assumed. Pragma Export_Function (and Export if present) must appear in the same declarative region as the function to which they apply. The Internal parameter must uniquely designate the function to which the pragma applies. If more than one function name exists of this name in the declarative part, then the use of the Parameter_Types and Result_Type parameters is mandatory to achieve the required unique designation. Subtype marks in these parameters must exactly match the subtypes in the corresponding function specification, using positional notation to match parameters with subtype marks. The Mechanism and Result_Mechanism parameters may optionally be used to specify passing mechanisms for the parameters and result. If a single mechanism name is given, then it applies to all parameters. Otherwise mechanisms can be specified on a parameter by parameter basis using either positional or named notation. If the mechanism is not specified, then the default mechanism is used. Note: pass by descriptor applies only to OpenVMS ports of GNAT pragma Export_Object [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Size =>] EXTERNAL_SYMBOL] This pragma designates an object as exported, and apart from the extended rules for exernal symbols, is identical in effect to the use of the normal Export pragma applied to an object. A separate Export pragma may be used (and it probably desirable from the point of view of portability), but is not required. The Size parameter is syntax checked, but otherwise ignored by GNAT. pragma Export_Procedure ( [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL,] [, [Parameter_Types =>] (PARAMETER_TYPES)] [, [Mechanism =>] MECHANISM]); This pragma is identical to Export_Function, except that it applies to a procedure rather than a function, and the parameters Result_Type and Result_Mechanism are not permitted. pragma Export_Valued_Procedure ( [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL,] [, [Parameter_Types =>] (PARAMETER_TYPES)] [, [Mechanism =>] MECHANISM]); This pragma is identical to Export_Procedure, except that the first parameter, which must be present, must be of mode OUT, and externally the subprogram is treated as a function with this parameter as the result of the function. The reason for this capability is to allow the use of OUT and IN OUT parameters in interfacing to external functions (which are not permitted in Ada functions). pragma Extend_System ([Name =>] IDENTIFIER); This pragma is used to provide backwards compatibility with other implementations that extend the facilities of package System. In GNAT, System contains only the definitions that are present in the Ada 95 RM. However, other implementations, notably the DEC Ada 83 implementation provide many extensions to package System. For each such implementation accomodated by this pragma, a package Aux_xxx is provided (e.g. Aux_DEC for the DEC Ada 93 implementation) which provides the required additional definitions. This package can be used in two ways. Either it can be with'ed in the normal way, and the entities accessed either by selection or using a use clause. In this case no special processing is required. However, if existing code contains references such as System.xxx where xxx is an entity in the extended definitions provided in package System, then this pragma may be used to extend visibility in System in a non-standard way that provides greater compatibility with the existing code. Pragma Extend_System is a configuration pragma whose single argument is the name of the package containing the extended definition (e.g. Aux_DEC for the DEC case). A unit compiled under control of this pragma will be processed using special visibility processing that looks in package System.Aux_xxx where Aux_xxx is the pragma argument for any entity referenced in package System, but not found in package System. pragma Import_Function ( [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Parameter_Types =>] (PARAMETER_TYPES)] [, [Result_Type =>] SUBTYPE_MARK] [, [Mechanism =>] MECHANISM] [, [Result_Mechanism =>] MECHANISM_NAME] [, [First_Optional_Parameter =>] IDENTIFIER]); PARAMETER_TYPES ::= null | SUBTYPE_MARK {, SUBTYPE_MARK} MECHANISM ::= MECHANISM_NAME | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) MECHANISM_ASSOCIATION ::= [formal_parameter_NAME =>] MECHANISM_NAME MECHANISM_NAME ::= Value | Reference | Descriptor [([Class =>] CLASS_NAME)] CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca This pragma is used in conjunction with a pragma Import to specify additional information for an imported function. The pragma Import (or equivalent pragma Interface) must precede the Import_Function pragma, and both must appear in the same declarative part as the function specification. The Internal parameter must uniquely designate the function to which the pragma applies. If more than one function name exists of this name in the declarative part, then the use of the Parameter_Types and Result_Type parameters is mandatory to achieve the required unique designation. Subtype marks in these parameters must exactly match the subtypes in the corresponding function specification, using positional notation to match parameters with subtype marks. The Mechanism and Result_Mechanism parameters may optionally be used to specify passing mechanisms for the parameters and result. If a single mechanism name is given, then it applies to all parameters. Otherwise mechanisms can be specified on a parameter by parameter basis using either positional or named notation. If the mechanism is not specified, then the default mechanism is used. Note: pass by descriptor applies only to OpenVMS ports of GNAT The First_Optional_Parameter applies only to OpenVMS ports of GNAT. It specifies that the designated parameter and all parameters that follow it are optional, meaning that they are not passed at the generated code level (this is distinct from the notion of optional parameters in Ada where the parameters are passed anyway with the designated optional parameters). All optional parameters must be of mode IN, and have default parameter values that are either known at compile time expressions, or uses of the 'Null_Parameter attribute. pragma Import_Object [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Size =>] EXTERNAL_SYMBOL] This pragma designates an object as imported, and apart from the extended rules for exernal symbols, is identical in effect to the use of the normal Import pragma applied to an object. Note that unlike the subprogram case, it is not necessary to use a separate Import pragma, although it is permissible to do so (and probably desirable from a portability point of view). The Size parameter is syntax checked, but otherwise ignored by GNAT. pragma Import_Procedure ( [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Parameter_Types =>] (PARAMETER_TYPES)] [, [Mechanism =>] MECHANISM] [, [First_Optional_Parameter =>] IDENTIFIER]); This pragma is identical to Import_Function, except that it applies to a procedure rather than a function, and the parameters Result_Type and Result_Mechanism are not permitted. pragma Import_Valued_Procedure ( [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Parameter_Types =>] (PARAMETER_TYPES)] [, [Mechanism =>] MECHANISM] [, [First_Optional_Parameter =>] IDENTIFIER]); This pragma is identical to Import_Procedure, except that the first parameter, which must be present, must be of mode OUT, and externally the subprogram is treated as a function with this parameter as the result of the function. The reason for this capability is to allow the use of OUT and IN OUT parameters in interfacing to external functions (which are not permitted in Ada functions). pragma Inline_Generic (generic_package_NAME) This is implemented for compatibility with Dec, and is recognized, but otherwise ignored by GNAT. pragma Interface_Name ( [Entity =>] LOCAL_NAME [,[External_Name =>] static_string_EXPRESSION]] [,[Link_Name =>] static_string_EXPRESSION]] ); This pragma is implementation (GNAT) defined. It is an alternative way of specifying the interface name for an interfaced subprogram, and is provided for compatibility with Ada 83 compilers that use the pragma for this purpose. At least one of the arguments external name or link name must be present. pragma Machine_Attribute ( [Attribute_Name =>] static_string_EXPRESSION ,[Entity =>] LOCAL_NAME ); This pragma is implementation (GNAT) defined. Machine dependent attributes can be specified for types and/or declarations. Currently only subprogram entities are supported. This pragma is semantically equivalent to __attribute__(( )) in Gnu C, where is recognized by the Gnu C macros: VALID_MACHINE_TYPE_ATTRIBUTE VALID_MACHINE_DECL_ATTRIBUTE, which are defined in the configuration header file tm.h. Further documentation can be found in the gcc distribution document: tm.texi. pragma No_Return (procedure_LOCAL_NAME); The given name must refer to one or more procedure declarations in the current declarative part. A procedure to which this pragma is applied may not contain any explicit return statements, and also may not contain any implicit return statements from falling off the end of a statement sequence. One use of this pragma is to identify procedures whose only purpose is to raise an exception. One use of this pragma is to suppress incorrect warnings about missing returns in functions, where the last statement of a function statement sequence is a call to such a procedure. pragma Share_Generic (generic_package_NAME) This is implemented for compatibility with Dec, and is recognized, but otherwise ignored by GNAT. pragma Source_File_Name ( [UNIT_NAME =>] unit_NAME, [BODY_FILE_NAME | SPEC_FILE_NAME] => STRING_LITERAL) The source file name pragma allows a program to override the normal naming convention. It is a configuration pragma, and so has the usual applicability of configuration pragmas (i.e. it applies to either an entire partition, or to all units in a compilation, or to a single unit, depending on how it is used. The form of the pragma is: The given unit name is mapped to the given file name. The identifier for the second argument is required, and indicates whether this is the file name for the spec or for the body. pragma Source_Reference (INTEGER_LITERAL [, STRING_LITERAL]); This pragma is implementation (GNAT) defined. It typically appears as the first line of a source file. The integer value is the logical line number of the line following the pragma line (for use in error messages and debugging information). The second argument is a static string constant that specifies the file name to be used in error messages and debugging information. This is most notably used for the output of gnatchop with the -r switch, to make sure that the original unchopped source file is the one referred to. Note: the second argument must be a string literal, it cannot be a static string expression other than a string literal. This is because its value is needed for error messages issued by all phases of the compiler. pragma Subtitle ([Subtitle =>] STRING_LITERAL) Syntax checked but otherwise ignored by GNAT. This is a listing control pragma that is used in DEC Ada implementations to provide a subtitle for the program listing. The program listing generated by GNAT does not have titles or subtitles. pragma Suppress_All This pragma can only appear immediately following a compilation unit. The effect is to apply Suppress (All_Checks) to the unit which it follows. This pragma is implemented for compatibility with DEC Ada usage. The use of pragma Suppress (All_Checks) as a normal configuration pragma is preferred usage in GNAT. pragma Task_Info (task_info_EXPRESSION) This pragma appears within a task definition (like pragma Priority) and applies to the task in which it appears. The argument must be of type System.Task_Info.Task_Info_Type. pragma Title (TITLING_OPTION [, TITLING OPTION]); TITLING_OPTION ::= [Title =>] STRING_LITERAL | [Subtitle =>] STRING_LITERAL Syntax checked but otherwise ignored by GNAT. This is a listing control pragma that is used in DEC Ada implementations to provide a title and/or subtitle for the program listing. The program listing generated by GNAT does not have titles or subtitles. Note: unlike other pragmas, the full flexibility of named notation is allowed for this pragma, i.e. the parameters may be given in any order if named notation is used, and named and positional notation can be mixed following the normal rules for procedure calls in Ada. pragma Unchecked_Union (first_subtype_LOCAL_NAME) This pragma is implementation (GNAT) defined. It is used to declare that the named type should be equivalent to a C union type, and is intended only for use in interfacing with C code that uses union types. In Ada terms, the named type must obey the following rules: It is a non-tagged non-limited record type It has a single discrete discriminant with a default value Pragma Suppress (Discriminant_Check) applies implicitly The component list consists of a single variant part The default convention is C Each variant has a component list with a single component No nested variants are allowed No component can have an explicit default value No component can have a non-static constraint In addition, given a type that meets the above requirements, the following restrictions apply to its use throughout the program: The discriminant name can be mentioned only in an aggregate No subtypes may be created of this type The type may not be constrained by giving a discriminant value An unchecked union type cannot be passed as the actual for a generic formal with a discriminant. Also, equality and inequality operations on unchecked_unions are not available, since there is no discriminant to compare, and in general the compiler does not even know how many bits to compare. It is implementation dependent whether this is detected at compile time as an illegality, or whether it is undetected and considered to be an erroneous construct. In GNAT, a direct comparison is illegal, but GNAT does not attempt to catch the composite case (where two composites are compared that contain an unchecked union component), so such comparisons are simply considered erroneous. The layout of the resulting type corresponds exactly to a C union, where each branch of the union corresponds to a single variant in the Ada record. The semantics of the Ada program is not changed in any way by the pragma, i.e. provided the above restrictions are followed, and no erroneous incorrect references to fields or erroneous comparisons occur, the semantics is exactly as described by the Ada reference manual. pragma Unimplemented_Unit; This pragma is implementation (GNAT) defined. If it occurs in a unit that is processed by the compiler, the compilation is aborted with the message xxx not implemented, where xxx is the name of the current compilation unit followed by a compiler abort. This pragma is intended to allow the compiler to handle unimplemented library units in a clean manner. The abort only hapens if code is being generated. This allows the use of specs of unimplemented packages in syntax or semantic checking mode. pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); This pragma is an implementation (GNAT) defined configuration pragma. It undoes the effect of a previous pragma Suppress. If there is no corresponding pragma Suppress in effect, then it has no effect. The range of the effect is the same as for pragma Suppress. The meaning of the arguments is identical to that used in pragma Suppress. One important application is to ensure that checks are on in cases where code depends on the checks for its correct functioning, so that the code will compile correctly even if the compiler switches are set to suppress checks. Pragma Warnings (On | Off, [LOCAL_NAME]); Normally warnings are enabled, with the output being controlled by the command line switch. Warnings (Off) turns off generation of warnings until a Warnings (On) is encountered or the end of the current unit. If generation of warnings is turned off using this pragma, then no warning messages are output, regardless of the setting of the command line switches. The form with a single argument is a configuration pragma. If a second parameter is present, then warnings are suppressed for the particular entity named in the pragma. This suppression is effective from the point where it occurs till the end of the extended scope of the variable (similar to the scope of Suppress). ========================================== = Description of GNAT-defined Attributes = ========================================== Abort_Signal Standard'Abort_Signal (Standard is the only allowed prefix) provides the entity for the special exception used to signal task abort or asynchronous transfer of control. Normally this attribute should only be used in the tasking runtime (it is highly peculiar, and completely outside the normal semantics of Ada, for a user program to intercept the abort exception). Address_Size Standard'Address_Size (Standard is the only allowed prefix) is a static constant giving the number of bits in an Address. It is used primarily for constructing the definition of Memory_Size in package Standard, but may be freely used in user programs. This is a static attribute. Bit Obj'Bit, where Obj is any object, yields the bit offset within the storage unit (byte) that contains the first bit of storage allocated for the object. The value of this attribute is of the type Universal_Integer, and is always a non-negative number not exceeding the value of System.Storage_Unit. For an object that is a variable or a constant allocated in a register, the value is zero. (The use of this attribute does not force the allocation of a variable to memory). For an object that is a formal parameter, this attribute applies to either the matching actual parameter or to a copy of the matching actual parameter. For an access object the value is zero. Note that Obj.all'Bit is subject to an Access_Check for the designated object. Similarly for a record component X.C'Bit is subject to a discriminant check and X(I).Bit and X(I1..I2)'Bit are subject to index checks. This attribute is designed to be compatible with the DEC Ada definition and implementation of the Bit attribute. Default_Bit_Order Standard'Default_Bit_Order (Standard is the only permissible prefix), provides the value System.Default_Bit_Order as a Pos value (0 for High_Order_First, 1 for Low_Order_First). This is used to construct the definition of Default_Bit_Order in package System. This is a static attribute. Elab_Body This attribute can only be applied to a program unit name. It returns the entity for the corresponding elaboration procedure for elaborating the body of the referenced unit. This is used in the main generated elaboration procedure by the binder, and is not normally used in any other context, but there may be specialized situations in which it is useful to be able to call this elaboration procedure from Ada code, e.g. if it is necessary to do selective reelaboration to fix some error. Elab_Spec This attribute can only be applied to a program unit name. It returns the entity for the corresponding elaboration procedure for elaborating the spec of the referenced unit. This is used in the main generated elaboration procedure by the binder, and is not normally used in any other context, but there may be specialized situations in which it is useful to be able to call this elaboration procedure from Ada code, e.g. if it is necessary to do selective reelaboration to fix some error. Enum_Rep For every enumeration subtype S, S'Enum_Rep denotes a function with the following specification: function S'Enum_Rep (Arg : S'Base) return universal_integer; The function returns the representation value for the given enumeration value. This will be equal to the 'Pos value in the absence of an enumeration representation clause. This is a static attribute (i.e. the result is static if the argument is static). Fixed_Value For every fixed-point type S, S'Fixed_Value denotes a function with the following specification: function S'Fixed_Value (Arg : universal_integer) return S; The value returned is the fixed-point value V such that V = Arg * S'Small The effect is thus equivalent to first converting the argument to the integer type used to represent S, and then doing an unchecked conversion to the fixed-point type. This attribute is primarily intended for use in implementation of the input-output functions for fixed-point values. Img The 'Img function is defined for any prefix, P, that denotes an object of scalar type T. P'Img is equivalent to T'Image (P). This is convenient for debugging. For example: Put_Line ("X = " & X'Img); has the same meaning as the more verbose: Put_Line ("X = " & Temperature_Type'Image (X)); where Temperature_Type is the subtype of the object X. Integer_Value For every integer type S, S'Integer_Value denotes a function with the following specification: function S'Integer_Value (Arg : universal_fixed) return S; The value returned is the integer value V, such that Arg = V * fixed-type'Small The effect is thus equivalent to first doing an unchecked convert from the fixed-point type to its corresponding implementation type, and then converting the result to the target integer type. This attribute is primarily intended for use in implementation of the standard input-output functions for fixed-point values. Machine_Size This attribute is identical to the Object_Size attribute. It is provided for compatibility with the DEC attribute of this name. Max_Interrupt_Priority Standard'Max_Interrupt_Priority (Standard is the only permissible prefix), provides the value System.Max_Interrupt_Priority, and is intended primarily for constructing this definition in package System (see note above in Default_Bit_Order description}. This is a static attribute. Max_Priority Standard'Max_Priority (Standard is the only permissible prefix) provides the value System.Max_Priority, and is intended primarily for constructing this definition in package System (see note above in Default_Bit_Order description). This is a static attribute. Maximum_Alignment Standard'Maximum_Alignment (Standard is the only permissible prefix) provides the maximum useful alignment value for the target. This is a static value that can be used to specify the alignment for an object, guaranteeing that it is properly aligned in all cases. The time this is useful is when an external object is imported and its alignment requirements are unknown. This is a static attribute. Mechanism_Code function'Mechanism_Code yeilds an integer code for the mechanism used for the result of function, and subprogram'Mechanism_Code (n) yields the mechanism used for formal parameter number n (a static integer value, 1 = first parameter). The code returned is: 1 = by copy (value) 2 = by reference 3 = by descriptor (default descriptor type) 4 = by descriptor (UBS unaligned bit string) 5 = by descriptor (UBSB aligned bit string with arbitrary bounds) 6 = by descriptor (UBA unaligned bit array) 7 = by descriptor (S string, also scalar access type parameter) 8 = by descriptor (SB string with arbitrary bounds) 9 = by descriptor (A contiguous array) 10 = by descriptor (NCA non-contiguous array) Note: values from 3-10 are only relevant to DEC OpenVMS implementations Null_Parameter A reference T'Null_Parameter denotes an (imaginary) object of type or subtype T allocated at (machine) address zero. The attribute is allowed only as the default expression of a formal parameter, or as an actual expression of a subporgram call. In either case, the subprogram must be imported. The identity of the object is represented by the address zero in the argument list, independent of the passing mechanism (explicit or default). The reason that this capability is needed is that for a record or other composite object passed by reference, there is no other way of specifying that a zero address should be passed. Object_Size Type'Object_Size is the same as Type'Size for all types except fixed-point types and discrete types. For fixed-point types and discrete types, this attribute gives the size used for default allocation of objects and components of the size. It may be set for any subtype (even a non-first subtype). See section on Size handling for further details. Passed_By_Reference T'Passed_By_Reference for any subtype T returns a boolean value that is true if the type is normally passed by reference and false if the type is normally passed by copy in calls. For scalar types, the result is always False and is static. For non-scalar types, the result is non-static (since it is computed by Gigi). Range_Length T'Range_Length for any discrete type T yields the number of values represented by the subtype (zero for a null range). The result is static for static subtypes. Note that Range_Length applied to the index subtype of a one dimensional array always gives the same result as Range applied to the array itself. Storage_Unit Standard'Storage_Unit (Standard is the only permissible prefix) provides the value System.Storage_Unit, and is intended primarily for constructing this definition in package System (see note above in Default_Bit_Order description). The is a static attribute. Tick Standard'Tick (Standard is the only permissible prefix) provides the value System.Tick, and is intended primarily for constructing this definition in package System (see note above in description of Default_Bit_Order). This is a static attribute. Type_Class T'Type_Class for any type or subtype T yields the value of the type class for the full type of T. If T is a generic formal type, then the value is the value for the corresponding actual subtype. The value of this attribute is of type System.Aux_DEC.Type_Class, which has the following definition: type Type_Class is (Type_Class_Enumeration, Type_Class_Integer, Type_Class_Fixed_Point, Type_Class_Floating_Point, Type_Class_Array, Type_Class_Record, Type_Class_Access, Type_Class_Task, Type_Class_Address); Protected types yield the value Type_Class_Task, which thus applies to all concurrent types. This attribute is designed to be compatible with the DEC Ada attribute of the same name. Universal_Literal_String The prefix of 'Universal_Literal_String must be a named number. The static result is the string consisting of the characters of the number as defined in the original source. This allows the user program to access the actual text of named numbers without intermediate conversions and without the need to enclose the strings in quotes (which would preclude their use as numbers). This is used internally for the construction of values of the floating-point attributes from the file ttypef.ads, but may also be used by user programs. Unrestricted_Access The Unrestricted_Access attribute is similar to Access except that all accessibility and aliased view checks are omitted. This is very much a user-beware attribute. Basically its status is very similar to Address, for which it is a desirable replacement where the value desired is an access type. In other words, its effect is identical to first taking 'Address and then doing an unchecked conversion to a desired access type. Note that in GNAT, but not necessarily in other implementations, the use of static chains for inner level subprograms means that Unrestricted_Access applied to a subprogram yields a value that can be called as long as the subprogram is in scope (normal Ada 95 accessibility rules restrict this usage). Value_Size Type'Value_Size is the number of bits required to represent a value of the given subtype. It is the same as Type'Size, but, unlike Size, may be set for non-first subtypes. See section on Size handling for further details. Word_Size Standard'Word_Size (Standard is the only permissible prefix) provides the value System.Word_Size, and is intended primarily for constructing this definition in package System (see note above in Default_Bit_Order description). This is a static attribute.