Next: , Previous: About This Guide, Up: Top


1 Implementation Defined Pragmas

Ada 95 defines a set of pragmas that can be used to supply additional information to the compiler. These language defined pragmas are implemented in GNAT and work as described in the Ada 95 Reference Manual.

In addition, Ada 95 allows implementations to define additional pragmas whose meaning is defined by the implementation. GNAT provides a number of these implementation-dependent pragmas which can be used to extend and enhance the functionality of the compiler. This section of the GNAT Reference Manual describes these additional pragmas.

Note that any program using these pragmas may not be portable to other compilers (although GNAT implements this set of pragmas on all platforms). Therefore if portability to other compilers is an important consideration, the use of these pragmas should be minimized.

pragma Abort_Defer
Syntax:
          pragma Abort_Defer;
     

This pragma 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).

pragma Ada_83
Syntax:
          pragma Ada_83;
     

A configuration pragma that establishes Ada 83 mode for the unit to which it applies, regardless of the mode set by the command line switches. In Ada 83 mode, GNAT attempts to be as compatible with the syntax and semantics of Ada 83, as defined in the original Ada 83 Reference Manual as possible. In particular, the new Ada 95 keywords are not recognized, optional package bodies are allowed, and generics may name types with unknown discriminants without using the (<>) notation. In addition, some but not all of the additional restrictions of Ada 83 are enforced.

Ada 83 mode is intended for two purposes. Firstly, it allows existing legacy Ada 83 code to be compiled and adapted to GNAT with less effort. Secondly, it aids in keeping code backwards compatible with Ada 83. However, there is no guarantee that code that is processed correctly by GNAT in Ada 83 mode will in fact compile and execute with an Ada 83 compiler, since GNAT does not enforce all the additional checks required by Ada 83.


pragma Ada_95
Syntax:
          pragma Ada_95;
     

A configuration pragma that establishes Ada 95 mode for the unit to which it applies, regardless of the mode set by the command line switches. This mode is set automatically for the Ada and System packages and their children, so you need not specify it in these contexts. This pragma is useful when writing a reusable component that itself uses Ada 95 features, but which is intended to be usable from either Ada 83 or Ada 95 programs.


pragma Annotate
Syntax:
          pragma Annotate (IDENTIFIER {, ARG});
          
          ARG ::= NAME | EXPRESSION
     

This pragma is used to annotate programs. identifier identifies the type of annotation. GNAT verifies this is an identifier, but does not otherwise analyze it. The arg argument can be either a string literal or an expression. 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, including ASIS.


pragma Assert
Syntax:
          pragma Assert (
            boolean_EXPRESSION
            [, static_string_EXPRESSION])
     

The effect of this pragma depends on whether the corresponding command line switch is set to activate assertions. The pragma expands into code equivalent to the following:

          if assertions-enabled then
             if not boolean_EXPRESSION then
                System.Assertions.Raise_Assert_Failure
                  (string_EXPRESSION);
             end if;
          end if;
     

The string argument, if given, is the message that will be associated with the exception occurrence if the exception is raised. 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. 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 that, as with the if statement to which it is equivalent, the type of the expression is either Standard.Boolean, or any type derived from this standard type.

If assertions are disabled (switch -gnata not used), then there is no effect (and in particular, any side effects from the expression are suppressed). More precisely it is not quite true that the pragma has no effect, since the expression is analyzed, and may cause types to be frozen if they are mentioned here for the first time.

If assertions are enabled, then the given expression is tested, and if it is False then System.Assertions.Raise_Assert_Failure is called which results in the raising of Assert_Failure with the given message.

If the boolean expression has side effects, 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. You should generally avoid side effects in the expression arguments of this pragma. However, the expressions are analyzed for semantic correctness whether or not assertions are enabled, so turning assertions on and off cannot affect the legality of a program.


pragma Ast_Entry
Syntax:
          pragma AST_Entry (entry_IDENTIFIER);
     

This pragma is implemented only in the OpenVMS implementation of GNAT. The argument is the simple name of a single entry; at most one AST_Entry pragma is allowed for any given entry. This pragma must be used in conjunction with the AST_Entry attribute, and is only allowed after the entry declaration and in the same task type specification or single task as the entry to which it applies. This pragma specifies that the given entry may be used to handle an OpenVMS asynchronous system trap (AST) resulting from an OpenVMS system service call. The pragma does not affect normal use of the entry. For further details on this pragma, see the DEC Ada Language Reference Manual, section 9.12a.


pragma C_Pass_By_Copy
Syntax:
          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). Use the configuration pragma C_Pass_By_Copy to change this default, by requiring that record formal parameters be passed by copy if all of the following conditions are met:

If these conditions are met 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).

You can also pass records by copy by specifying the convention C_Pass_By_Copy for the record type, or by using the extended Import and Export pragmas, which allow specification of passing mechanisms on a parameter by parameter basis.


pragma Comment
Syntax:
          pragma Comment (static_string_EXPRESSION);
     

This is almost identical in effect to pragma Ident. It allows the placement of a comment into the object file and hence into the executable file if the operating system permits such usage. The difference is that Comment, unlike Ident, has no limit on the length of the string argument, and no limitations on placement of the pragma (it can be placed anywhere in the main source unit).


pragma Common_Object
Syntax:
          pragma Common_Object (
               [Internal =>] LOCAL_NAME,
            [, [External =>] EXTERNAL_SYMBOL]
            [, [Size     =>] EXTERNAL_SYMBOL] )
          
          EXTERNAL_SYMBOL ::=
            IDENTIFIER
          | static_string_EXPRESSION
     

This pragma enables the shared use of variables stored in overlaid linker areas corresponding to the use of COMMON in Fortran. The single object local_name is assigned to the area designated by the External argument. You may define a record to correspond to a series of fields. The size argument is syntax checked in GNAT, but otherwise ignored.

Common_Object is not supported on all platforms. If no support is available, then the code generator will issue a message indicating that the necessary attribute for implementation of this pragma is not available.


pragma Complex_Representation
Syntax:
          pragma Complex_Representation
                  ([Entity =>] LOCAL_NAME);
     

The Entity argument must be the name of a record type which has two fields of the same floating-point type. The effect of this pragma is to force gcc to use the special internal complex representation form for this record, which may be more efficient. Note that this may result in the code for this type not conforming to standard ABI (application binary interface) requirements for the handling of record types. For example, in some environments, there is a requirement for passing records by pointer, and the use of this pragma may result in passing this type in floating-point registers.


pragma Component_Alignment
Syntax:
          pragma Component_Alignment (
               [Form =>] ALIGNMENT_CHOICE
            [, [Name =>] type_LOCAL_NAME]);
          
          ALIGNMENT_CHOICE ::=
            Component_Size
          | Component_Size_4
          | Storage_Unit
          | Default
     

Specifies the alignment of components in array or record types. The meaning of the Form argument is as follows:

Component_Size
Aligns scalar components and subcomponents of the array or record type 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
Naturally aligns components with a size of four or fewer bytes. 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 underlying hardware or operating system or both. For OpenVMS VAX systems, the Default choice is the same as the Storage_Unit choice (byte alignment). For all other systems, the Default choice is the same as Component_Size (natural alignment).

If the Name parameter is present, type_local_name 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 a pragma 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, 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.

If the alignment for a record or array type is not specified (using pragma Pack, pragma Component_Alignment, or a record rep clause), the GNAT uses the default alignment as described previously.


pragma Convention_Identifier
Syntax:
          pragma Convention_Identifier (
                   [Name =>]       IDENTIFIER,
                   [Convention =>] convention_IDENTIFIER);
     

This pragma provides a mechanism for supplying synonyms for existing convention identifiers. The Name identifier can subsequently be used as a synonym for the given convention in other pragmas (including for example pragma Import or another Convention_Identifier pragma). As an example of the use of this, suppose you had legacy code which used Fortran77 as the identifier for Fortran. Then the pragma:

          pragma Convention_Indentifier (Fortran77, Fortran);
     

would allow the use of the convention identifier Fortran77 in subsequent code, avoiding the need to modify the sources. As another example, you could use this to parametrize convention requirements according to systems. Suppose you needed to use Stdcall on windows systems, and C on some other system, then you could define a convention identifier Library and use a single Convention_Identifier pragma to specify which convention would be used system-wide.


pragma CPP_Class
Syntax:
          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 laid 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 specified 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 CPP_Class is intended primarily for automatic generation using an automatic binding generator tool. See Interfacing to C++ for related information.


pragma CPP_Constructor
Syntax:
          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 argument is a name that must have been previously mentioned in a pragma Import with Convention = CPP, and must be of one of the following forms:

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:

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 issues the appropriate call, whatever it is, to get the object properly initialized.

In the case of derived objects, you may use one of two possible forms for declaring and creating an object:

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.

If no constructors are imported, it is impossible to create any objects on the Ada side. If no default constructor is imported, only the initialization forms using an explicit call to a constructor are permitted.

Pragma CPP_Constructor is intended primarily for automatic generation using an automatic binding generator tool. See Interfacing to C++ for more related information.


pragma CPP_Virtual
Syntax:
          pragma CPP_Virtual
               [Entity     =>] ENTITY,
            [, [Vtable_Ptr =>] vtable_ENTITY,]
            [, [Position   =>] static_integer_EXPRESSION])
     

This pragma serves the same function as pragma Import in that case of a virtual function imported from C++. The Entity argument must be a primitive subprogram of a tagged type to which pragma CPP_Class applies. The Vtable_Ptr argument specifies the Vtable_Ptr component which contains the entry for this virtual function. The Position argument 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. In that case the compiler can deduce both these values.

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_Virtual is intended primarily for automatic generation using an automatic binding generator tool. See Interfacing to C++ for related information.


pragma CPP_Vtable
Syntax:
          pragma CPP_Vtable (
            [Entity      =>] ENTITY,
            [Vtable_Ptr  =>] vtable_ENTITY,
            [Entry_Count =>] static_integer_EXPRESSION);
     

Given a record to which the pragma CPP_Class applies, this pragma can be specified for each component of type CPP.Interfaces.Vtable_Ptr. 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 these functions need to be imported on the Ada side.

You may 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 CPP_Vtable is intended primarily for automatic generation using an automatic binding generator tool. See Interfacing to C++ for related information.


pragma Debug
Syntax:
          pragma Debug (PROCEDURE_CALL_WITHOUT_SEMICOLON);
          
          PROCEDURE_CALL_WITHOUT_SEMICOLON ::=
            PROCEDURE_NAME
          | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART
     

The argument has the syntactic form of an expression, meeting the syntactic requirements for pragmas.

If assertions are not enabled on the command line, this pragma has no effect. If asserts are enabled, the semantics of the pragma is exactly equivalent to the procedure call statement corresponding to the argument with a terminating semicolon. Pragmas are permitted in sequences of declarations, so you can use pragma Debug to intersperse calls to debug procedures in the middle of declarations.


pragma Elaboration_Checks
Syntax:
          pragma Elaboration_Checks (RM | Static);
     

This is a configuration pragma that provides control over the elaboration model used by the compilation affected by the pragma. If the parameter is RM, then the dynamic elaboration model described in the Ada Reference Manual is used, as though the -gnatE switch had been specified on the command line. If the parameter is Static, then the default GNAT static model is used. This configuration pragma overrides the setting of the command line. For full details on the elaboration models used by the GNAT compiler, see section “Elaboration Order Handling in GNAT” in the GNAT User's Guide.


pragma Eliminate
Syntax:
          pragma Eliminate (
              [Unit_Name =>] IDENTIFIER |
                             SELECTED_COMPONENT);
          
          pragma Eliminate (
              [Unit_Name       =>]  IDENTIFIER |
                                    SELECTED_COMPONENT,
              [Entity          =>]  IDENTIFIER |
                                    SELECTED_COMPONENT |
                                    STRING_LITERAL
            [,[Parameter_Types =>]  PARAMETER_TYPES]
            [,[Result_Type     =>]  result_SUBTYPE_NAME]
            [,[Homonym_Number  =>]  INTEGER_LITERAL]);
          
          PARAMETER_TYPES ::= (SUBTYPE_NAME {, SUBTYPE_NAME})
          SUBTYPE_NAME    ::= STRING_LITERAL
     

This pragma indicates that the given entity is not used outside the compilation unit it is defined in. The entity may be either a subprogram or a variable.

If the entity to be eliminated is a library level subprogram, then the first form of pragma Eliminate is used with only a single argument. In this form, the Unit_Name argument specifies the name of the library level unit to be eliminated.

In all other cases, both Unit_Name and Entity arguments are required. item is an entity of a library package, then the first argument specifies the unit name, and the second argument specifies the particular entity. If the second argument is in string form, it must correspond to the internal manner in which GNAT stores entity names (see compilation unit Namet in the compiler sources for details).

The remaining parameters are optionally used to distinguish between overloaded subprograms. There are two ways of doing this.

Use Parameter_Types and Result_Type to specify the profile of the subprogram to be eliminated in a manner similar to that used for the extended Import and Export pragmas, except that the subtype names are always given as string literals, again corresponding to the internal manner in which GNAT stores entity names.

Alternatively, the Homonym_Number parameter is used to specify which overloaded alternative is to be eliminated. A value of 1 indicates the first subprogram (in lexical order), 2 indicates the second etc.

The effect of the pragma is to allow the compiler to eliminate the code or data associated with the named entity. Any reference to an eliminated entity outside the compilation unit it is defined in, causes a compile time or link time error.

The parameters of this pragma may be given in any order, as long as the usual rules for use of named parameters and position parameters are used.

The intention of pragma Eliminate is to allow a program to be compiled in a system independent manner, with unused entities eliminated, without the requirement of modifying the source text. Normally the required set of Eliminate pragmas is constructed automatically using the gnatelim tool. Elimination of unused entities local to a compilation unit is automatic, without requiring the use of pragma Eliminate.

Note that the reason this pragma takes string literals where names might be expected is that a pragma Eliminate can appear in a context where the relevant names are not visible.


pragma Export_Exception
Syntax:
          pragma Export_Exception (
               [Internal =>] LOCAL_NAME,
            [, [External =>] EXTERNAL_SYMBOL,]
            [, [Form     =>] Ada | VMS]
            [, [Code     =>] static_integer_EXPRESSION]);
          
          EXTERNAL_SYMBOL ::=
            IDENTIFIER
          | static_string_EXPRESSION
     

This pragma is implemented only in the OpenVMS implementation of GNAT. It causes the specified exception to be propagated outside of the Ada program, so that it can be handled by programs written in other OpenVMS languages. This pragma establishes an external name for an Ada exception and makes the name available to the OpenVMS Linker as a global symbol. For further details on this pragma, see the DEC Ada Language Reference Manual, section 13.9a3.2.


pragma Export_Function ...
Syntax:
          pragma Export_Function (
               [Internal         =>] LOCAL_NAME,
            [, [External         =>] EXTERNAL_SYMBOL]
            [, [Parameter_Types  =>] PARAMETER_TYPES]
            [, [Result_Type      =>] result_SUBTYPE_MARK]
            [, [Mechanism        =>] MECHANISM]
            [, [Result_Mechanism =>] MECHANISM_NAME]);
          
          EXTERNAL_SYMBOL ::=
            IDENTIFIER
          | static_string_EXPRESSION
          
          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
     

Use this pragma to make a function externally callable and optionally provide information on mechanisms to be used for passing parameter and result values. We recommend, for the purposes of improving portability, this pragma always be used in conjunction with a separate pragma Export, which must precede the pragma Export_Function. GNAT does not require a separate pragma Export, but if none is present, Convention Ada is assumed, which is usually not what is wanted, so it is usually appropriate to use this pragma in conjunction with a Export or Convention pragma that specifies the desired foreign convention. Pragma Export_Function (and Export, if present) must appear in the same declarative region as the function to which they apply.

internal_name must uniquely designate the function to which the pragma applies. If more than one function name exists of this name in the declarative part you must use 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. Passing by descriptor is supported only on the OpenVMS ports of GNAT.


pragma Export_Object ...
Syntax:
          pragma Export_Object
                [Internal =>] LOCAL_NAME,
             [, [External =>] EXTERNAL_SYMBOL]
             [, [Size     =>] EXTERNAL_SYMBOL]
          
          EXTERNAL_SYMBOL ::=
            IDENTIFIER
          | static_string_EXPRESSION
     

This pragma designates an object as exported, and apart from the extended rules for external symbols, is identical in effect to the use of the normal Export pragma applied to an object. You may use a separate Export pragma (and you probably should from the point of view of portability), but it is not required. Size is syntax checked, but otherwise ignored by GNAT.


pragma Export_Procedure ...
Syntax:
          pragma Export_Procedure (
               [Internal        =>] LOCAL_NAME
            [, [External        =>] EXTERNAL_SYMBOL]
            [, [Parameter_Types =>] PARAMETER_TYPES]
            [, [Mechanism       =>] MECHANISM]);
          
          EXTERNAL_SYMBOL ::=
            IDENTIFIER
          | static_string_EXPRESSION
          
          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 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. GNAT does not require a separate pragma Export, but if none is present, Convention Ada is assumed, which is usually not what is wanted, so it is usually appropriate to use this pragma in conjunction with a Export or Convention pragma that specifies the desired foreign convention.


pragma Export_Valued_Procedure
Syntax:
          pragma Export_Valued_Procedure (
               [Internal        =>] LOCAL_NAME
            [, [External        =>] EXTERNAL_SYMBOL]
            [, [Parameter_Types =>] PARAMETER_TYPES]
            [, [Mechanism       =>] MECHANISM]);
          
          EXTERNAL_SYMBOL ::=
            IDENTIFIER
          | static_string_EXPRESSION
          
          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 identical to Export_Procedure except that the first parameter of local_name, 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. GNAT provides for this capability to allow the use of OUT and IN OUT parameters in interfacing to external functions (which are not permitted in Ada functions). GNAT does not require a separate pragma Export, but if none is present, Convention Ada is assumed, which is almost certainly not what is wanted since the whole point of this pragma is to interface with foreign language functions, so it is usually appropriate to use this pragma in conjunction with a Export or Convention pragma that specifies the desired foreign convention.


pragma Extend_System
Syntax:
          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 accommodated by this pragma, GNAT provides a package Aux_xxx, e.g. Aux_DEC for the DEC Ada 83 implementation, which provides the required additional definitions. You can use this package in two ways. You can with it in the normal way and access entities 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, you may use this pragma 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 Ada 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.

You can use this pragma either to access a predefined System extension supplied with the compiler, for example Aux_DEC or you can construct your own extension unit following the above definition. Note that such a package is a child of System and thus is considered part of the implementation. To compile it you will have to use the appropriate switch for compiling system units. See the GNAT User's Guide for details.


pragma External
Syntax:
          pragma External (
            [   Convention    =>] convention_IDENTIFIER,
            [   Entity        =>] local_NAME
            [, [External_Name =>] static_string_EXPRESSION ]
            [, [Link_Name     =>] static_string_EXPRESSION ]);
     

This pragma is identical in syntax and semantics to pragma Export as defined in the Ada Reference Manual. It is provided for compatibility with some Ada 83 compilers that used this pragma for exactly the same purposes as pragma Export before the latter was standardized.


pragma External_Name_Casing
Syntax:
          pragma External_Name_Casing (
            Uppercase | Lowercase
            [, Uppercase | Lowercase | As_Is]);
     

This pragma provides control over the casing of external names associated with Import and Export pragmas. There are two cases to consider:

Implicit external names
Implicit external names are derived from identifiers. The most common case arises when a standard Ada 95 Import or Export pragma is used with only two arguments, as in:
                  pragma Import (C, C_Routine);
          

Since Ada is a case insensitive language, the spelling of the identifier in the Ada source program does not provide any information on the desired casing of the external name, and so a convention is needed. In GNAT the default treatment is that such names are converted to all lower case letters. This corresponds to the normal C style in many environments. The first argument of pragma External_Name_Casing can be used to control this treatment. If Uppercase is specified, then the name will be forced to all uppercase letters. If Lowercase is specified, then the normal default of all lower case letters will be used.

This same implicit treatment is also used in the case of extended DEC Ada 83 compatible Import and Export pragmas where an external name is explicitly specified using an identifier rather than a string.

Explicit external names
Explicit external names are given as string literals. The most common case arises when a standard Ada 95 Import or Export pragma is used with three arguments, as in:
               pragma Import (C, C_Routine, "C_routine");
          

In this case, the string literal normally provides the exact casing required for the external name. The second argument of pragma External_Name_Casing may be used to modify this behavior. If Uppercase is specified, then the name will be forced to all uppercase letters. If Lowercase is specified, then the name will be forced to all lowercase letters. A specification of As_Is provides the normal default behavior in which the casing is taken from the string provided.

This pragma may appear anywhere that a pragma is valid. In particular, it can be used as a configuration pragma in the gnat.adc file, in which case it applies to all subsequent compilations, or it can be used as a program unit pragma, in which case it only applies to the current unit, or it can be used more locally to control individual Import/Export pragmas.

It is primarily intended for use with OpenVMS systems, where many compilers convert all symbols to upper case by default. For interfacing to such compilers (e.g. the DEC C compiler), it may be convenient to use the pragma:

          pragma External_Name_Casing (Uppercase, Uppercase);
     

to enforce the upper casing of all external symbols.


pragma Finalize_Storage_Only
Syntax:
          pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);
     

This pragma allows the compiler not to emit a Finalize call for objects defined at the library level. This is mostly useful for types where finalization is only used to deal with storage reclamation since in most environments it is not necessary to reclaim memory just before terminating execution, hence the name.


pragma Float_Representation
Syntax:
          pragma Float_Representation (FLOAT_REP);
          
          FLOAT_REP ::= VAX_Float | IEEE_Float
     

This pragma is implemented only in the OpenVMS implementation of GNAT. It allows control over the internal representation chosen for the predefined floating point types declared in the packages Standard and System. For further details on this pragma, see the DEC Ada Language Reference Manual, section 3.5.7a. Note that to use this pragma, the standard runtime libraries must be recompiled. See the description of the GNAT LIBRARY command in the OpenVMS version of the GNAT Users Guide for details on the use of this command.


pragma Ident
Syntax:
          pragma Ident (static_string_EXPRESSION);
     

This pragma provides a string identification in the generated object file, if the system supports the concept of this kind of identification string. The maximum permitted length of the string literal is 31 characters. This pragma is allowed only in the outermost declarative part or declarative items of a compilation unit. On OpenVMS systems, the effect of the pragma is identical to the effect of the DEC Ada 83 pragma of the same name.


pragma Import_Exception
Syntax:
          pragma Import_Exception (
               [Internal =>] LOCAL_NAME,
            [, [External =>] EXTERNAL_SYMBOL,]
            [, [Form     =>] Ada | VMS]
            [, [Code     =>] static_integer_EXPRESSION]);
          
          EXTERNAL_SYMBOL ::=
            IDENTIFIER
          | static_string_EXPRESSION
     

This pragma is implemented only in the OpenVMS implementation of GNAT. It allows OpenVMS conditions (for example, from OpenVMS system services or other OpenVMS languages) to be propagated to Ada programs as Ada exceptions. The pragma specifies that the exception associated with an exception declaration in an Ada program be defined externally (in non-Ada code). For further details on this pragma, see the DEC Ada Language Reference Manual, section 13.9a.3.1.


pragma Import_Function ...
Syntax:
          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]);
          
          EXTERNAL_SYMBOL ::=
            IDENTIFIER
          | static_string_EXPRESSION
          
          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_Name argument must uniquely designate the function to which the pragma applies. If more than one function name exists of this name in the declarative part you must use the Parameter_Types and Result_Type parameters 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.

You may optionally use the Mechanism and Result_Mechanism parameters to specify passing mechanisms for the parameters and result. If you specify a single mechanism name, it applies to all parameters. Otherwise you may specify a mechanism on a parameter by parameter basis using either positional or named notation. If the mechanism is not specified, the default mechanism is used.

Passing by descriptor is supported only on the to OpenVMS ports of GNAT.

First_Optional_Parameter applies only to OpenVMS ports of GNAT. It specifies that the designated parameter and all following parameters 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
Syntax:
          pragma Import_Object
               [Internal =>] LOCAL_NAME,
            [, [External =>] EXTERNAL_SYMBOL],
            [, [Size     =>] EXTERNAL_SYMBOL])
          
          EXTERNAL_SYMBOL ::=
            IDENTIFIER
          | static_string_EXPRESSION
     

This pragma designates an object as imported, and apart from the extended rules for external symbols, is identical in effect to the use of the normal Import pragma applied to an object. Unlike the subprogram case, you need not use a separate Import pragma, although you may do so (and probably should do so from a portability point of view). size is syntax checked, but otherwise ignored by GNAT.


pragma Import_Procedure
Syntax:
          pragma Import_Procedure (
               [Internal                 =>] LOCAL_NAME,
            [, [External                 =>] EXTERNAL_SYMBOL]
            [, [Parameter_Types          =>] PARAMETER_TYPES]
            [, [Mechanism                =>] MECHANISM]
            [, [First_Optional_Parameter =>] IDENTIFIER]);
          
          EXTERNAL_SYMBOL ::=
            IDENTIFIER
          | static_string_EXPRESSION
          
          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 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 ...
Syntax:
          pragma Import_Valued_Procedure (
               [Internal                 =>] LOCAL_NAME,
            [, [External                 =>] EXTERNAL_SYMBOL]
            [, [Parameter_Types          =>] PARAMETER_TYPES]
            [, [Mechanism                =>] MECHANISM]
            [, [First_Optional_Parameter =>] IDENTIFIER]);
          
          EXTERNAL_SYMBOL ::=
            IDENTIFIER
          | static_string_EXPRESSION
          
          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 identical to Import_Procedure except that the first parameter of local_name, 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 purpose of 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). You may optionally use the Mechanism parameters to specify passing mechanisms for the parameters. If you specify a single mechanism name, it applies to all parameters. Otherwise you may specify a mechanism on a parameter by parameter basis using either positional or named notation. If the mechanism is not specified, the default mechanism is used.

Note that it is important to use this pragma in conjunction with a separate pragma Import that specifies the desired convention, since otherwise the default convention is Ada, which is almost certainly not what is required.


pragma Initialize_Scalars
Syntax:
          pragma Initialize_Scalars;
     

This pragma is similar to Normalize_Scalars conceptually but has two important differences. First, there is no requirement for the pragma to be used uniformly in all units of a partition, in particular, it is fine to use this just for some or all of the application units of a partition, without needing to recompile the run-time library.

In the case where some units are compiled with the pragma, and some without, then a declaration of a variable where the type is defined in package Standard or is locally declared will always be subject to initialization, as will any declaration of a scalar variable. For composite variables, whether the variable is initialized may also depend on whether the package in which the type of the variable is declared is compiled with the pragma.

The other important difference is that there is control over the value used for initializing scalar objects. At bind time, you can select whether to initialize with invalid values (like Normalize_Scalars), or with high or low values, or with a specified bit pattern. See the users guide for binder options for specifying these cases.

This means that you can compile a program, and then without having to recompile the program, you can run it with different values being used for initializing otherwise uninitialized values, to test if your program behavior depends on the choice. Of course the behavior should not change, and if it does, then most likely you have an erroneous reference to an uninitialized value.

Note that pragma Initialize_Scalars is particularly useful in conjunction with the enhanced validity checking that is now provided in GNAT, which checks for invalid values under more conditions. Using this feature (see description of the -gnatv flag in the users guide) in conjunction with pragma Initialize_Scalars provides a powerful new tool to assist in the detection of problems caused by uninitialized variables.


pragma Inline_Always
Syntax:
          pragma Inline_Always (NAME [, NAME]);
     

Similar to pragma Inline except that inlining is not subject to the use of option -gnatn for inter-unit inlining.


pragma Inline_Generic
Syntax:
          pragma Inline_Generic (generic_package_NAME)
     

This is implemented for compatibility with DEC Ada 83 and is recognized, but otherwise ignored, by GNAT. All generic instantiations are inlined by default when using GNAT.


pragma Interface
Syntax:
          pragma Interface (
               [Convention    =>] convention_identifier,
               [Entity =>] local_name
            [, [External_Name =>] static_string_expression],
            [, [Link_Name     =>] static_string_expression]);
     

This pragma is identical in syntax and semantics to the standard Ada 95 pragma Import. It is provided for compatibility with Ada 83. The definition is upwards compatible both with pragma Interface as defined in the Ada 83 Reference Manual, and also with some extended implementations of this pragma in certain Ada 83 implementations.


pragma Interface_Name
Syntax:
          pragma Interface_Name (
               [Entity        =>] LOCAL_NAME
            [, [External_Name =>] static_string_EXPRESSION]
            [, [Link_Name     =>] static_string_EXPRESSION]);
     

This pragma provides 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. You must provide at least one of External_Name or Link_Name.


pragma License
Syntax:
          pragma License (Unrestricted | GPL | Modified_GPL | Restricted);
     

This pragma is provided to allow automated checking for appropriate license conditions with respect to the standard and modified GPL. A pragma License, which is a configuration pragma that typically appears at the start of a source file or in a separate gnat.adc file, specifies the licensing conditions of a unit as follows:

Normally a unit with no License pragma is considered to have an unknown license, and no checking is done. However, standard GNAT headers are recognized, and license information is derived from them as follows.

These default actions means that a program with a restricted license pragma will automatically get warnings if a GPL unit is inappropriately with'ed. For example, the program:

          with Sem_Ch3;
          with GNAT.Sockets;
          procedure Secret_Stuff is
          ...
          end Secret_Stuff
     

if compiled with pragma License (Restricted) in a gnat.adc file will generate the warning:

          1.  with Sem_Ch3;
                  |
             >>> license of withed unit "Sem_Ch3" is incompatible
          
          2.  with GNAT.Sockets;
          3.  procedure Secret_Stuff is
     

Here we get a warning on Sem_Ch3 since it is part of the GNAT compiler and is licensed under the GPL, but no warning for GNAT.Sockets which is part of the GNAT run time, and is therefore licensed under the modified GPL.


pragma Link_With
Syntax:
          pragma Link_With (static_string_EXPRESSION {,static_string_EXPRESSION});
     

This pragma is provided for compatibility with certain Ada 83 compilers. It has exactly the same effect as pragma Linker_Options except that spaces occurring within one of the string expressions are treated as separators. For example, in the following case:

          pragma Link_With ("-labc -ldef");
     

results in passing the strings -labc and -ldef as two separate arguments to the linker. In addition pragma Link_With allows multiple arguments, with the same effect as successive pragmas.


pragma Linker_Alias
Syntax:
          pragma Linker_Alias (
            [Entity =>] LOCAL_NAME
            [Alias  =>] static_string_EXPRESSION);
     

This pragma establishes a linker alias for the given named entity. For further details on the exact effect, consult the GCC manual.


pragma Linker_Section
Syntax:
          pragma Linker_Section (
            [Entity  =>] LOCAL_NAME
            [Section =>] static_string_EXPRESSION);
     

This pragma specifies the name of the linker section for the given entity. For further details on the exact effect, consult the GCC manual.


pragma No_Run_Time
Syntax:
          pragma No_Run_Time;
     

This is a configuration pragma that makes sure the user code does not use nor need anything from the GNAT run time. This is mostly useful in context where code certification is required. Please consult the GNAT Pro High-Integrity Edition User's Guide for additional information.


pragma Normalize_Scalars
Syntax:
          pragma Normalize_Scalars;
     

This is a language defined pragma which is fully implemented in GNAT. The effect is to cause all scalar objects that are not otherwise initialized to be initialized. The initial values are implementation dependent and are as follows:

Standard.Character
Objects whose root type is Standard.Character are initialized to Character'Last. This will be out of range of the subtype only if the subtype range excludes this value.
Standard.Wide_Character
Objects whose root type is Standard.Wide_Character are initialized to Wide_Character'Last. This will be out of range of the subtype only if the subtype range excludes this value.
Integer types
Objects of an integer type are initialized to base_type'First, where base_type is the base type of the object type. This will be out of range of the subtype only if the subtype range excludes this value. For example, if you declare the subtype:
               subtype Ityp is integer range 1 .. 10;
          

then objects of type x will be initialized to Integer'First, a negative number that is certainly outside the range of subtype Ityp.

Real types
Objects of all real types (fixed and floating) are initialized to base_type'First, where base_Type is the base type of the object type. This will be out of range of the subtype only if the subtype range excludes this value.
Modular types
Objects of a modular type are initialized to typ'Last. This will be out of range of the subtype only if the subtype excludes this value.
Enumeration types
Objects of an enumeration type are initialized to all one-bits, i.e. to the value 2 ** typ'Size - 1. This will be out of range of the enumeration subtype in all cases except where the subtype contains exactly 2**8, 2**16, or 2**32 elements.


pragma Long_Float
Syntax:
          pragma Long_Float (FLOAT_FORMAT);
          
          FLOAT_FORMAT ::= D_Float | G_Float
     

This pragma is implemented only in the OpenVMS implementation of GNAT. It allows control over the internal representation chosen for the predefined type Long_Float and for floating point type representations with digits specified in the range 7 through 15. For further details on this pragma, see the DEC Ada Language Reference Manual, section 3.5.7b. Note that to use this pragma, the standard runtime libraries must be recompiled. See the description of the GNAT LIBRARY command in the OpenVMS version of the GNAT User's Guide for details on the use of this command.


pragma Machine_Attribute ...
Syntax:
          pragma Machine_Attribute (
            [Attribute_Name =>] string_EXPRESSION,
            [Entity         =>] LOCAL_NAME);
     

Machine dependent attributes can be specified for types and/or declarations. Currently only subprogram entities are supported. This pragma is semantically equivalent to __attribute__((string_expression)) in GNU C, where string_expression is recognized by the GNU C macros VALID_MACHINE_TYPE_ATTRIBUTE and VALID_MACHINE_DECL_ATTRIBUTE which are defined in the configuration header file tm.h for each machine. See the GCC manual for further information.


pragma Main_Storage
Syntax:
          pragma Main_Storage
            (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]);
          
          MAIN_STORAGE_OPTION ::=
            [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION
          | [TOP_GUARD       =>] static_SIMPLE_EXPRESSION
          
     

This pragma is provided for compatibility with OpenVMS Vax Systems. It has no effect in GNAT, other than being syntax checked. Note that the pragma also has no effect in DEC Ada 83 for OpenVMS Alpha Systems.


pragma No_Return
Syntax:
          pragma No_Return (procedure_LOCAL_NAME);
     

procedure_local_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.

Another 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 Passive
Syntax:
          pragma Passive ([Semaphore | No]);
     

Syntax checked, but otherwise ignored by GNAT. This is recognized for compatibility with DEC Ada 83 implementations, where it is used within a task definition to request that a task be made passive. If the argument Semaphore is present, or no argument is omitted, then DEC Ada 83 treats the pragma as an assertion that the containing task is passive and that optimization of context switch with this task is permitted and desired. If the argument No is present, the task must not be optimized. GNAT does not attempt to optimize any tasks in this manner (since protected objects are available in place of passive tasks).


pragma Polling
Syntax:
          pragma Polling (ON | OFF);
     

This pragma controls the generation of polling code. This is normally off. If pragma Polling (ON) is used then periodic calls are generated to the routine Ada.Exceptions.Poll. This routine is a separate unit in the runtime library, and can be found in file a-excpol.adb.

Pragma Polling can appear as a configuration pragma (for example it can be placed in the gnat.adc file) to enable polling globally, or it can be used in the statement or declaration sequence to control polling more locally.

A call to the polling routine is generated at the start of every loop and at the start of every subprogram call. This guarantees that the Poll routine is called frequently, and places an upper bound (determined by the complexity of the code) on the period between two Poll calls.

The primary purpose of the polling interface is to enable asynchronous aborts on targets that cannot otherwise support it (for example Windows NT), but it may be used for any other purpose requiring periodic polling. The standard version is null, and can be replaced by a user program. This will require re-compilation of the Ada.Exceptions package that can be found in files a-except.ads and a-except.adb.

A standard alternative unit (in file 4wexcpol.adb in the standard GNAT distribution) is used to enable the asynchronous abort capability on targets that do not normally support the capability. The version of Poll in this file makes a call to the appropriate runtime routine to test for an abort condition.

Note that polling can also be enabled by use of the -gnatP switch. See the GNAT User's Guide for details.


pragma Propagate_Exceptions
Syntax:
          pragma Propagate_Exceptions (subprogram_LOCAL_NAME);
     

This pragma indicates that the given entity, which is the name of an imported foreign-language subprogram may receive an Ada exception, and that the exception should be propagated. It is relevant only if zero cost exception handling is in use, and is thus never needed if the alternative longjmp / setjmp implementation of exceptions is used (although it is harmless to use it in such cases).

The implementation of fast exceptions always properly propagates exceptions through Ada code, as described in the Ada Reference Manual. However, this manual is silent about the propagation of exceptions through foreign code. For example, consider the situation where P1 calls P2, and P2 calls P3, where P1 and P3 are in Ada, but P2 is in C. P3 raises an Ada exception. The question is whether or not it will be propagated through P2 and can be handled in P1.

For the longjmp / setjmp implementation of exceptions, the answer is always yes. For some targets on which zero cost exception handling is implemented, the answer is also always yes. However, there are some targets, notably in the current version all x86 architecture targets, in which the answer is that such propagation does not happen automatically. If such propagation is required on these targets, it is mandatory to use Propagate_Exceptions to name all foreign language routines through which Ada exceptions may be propagated.


pragma Psect_Object
Syntax:
          pragma Psect_Object
               [Internal =>] LOCAL_NAME,
            [, [External =>] EXTERNAL_SYMBOL]
            [, [Size     =>] EXTERNAL_SYMBOL]
          
          EXTERNAL_SYMBOL ::=
            IDENTIFIER
          | static_string_EXPRESSION
     

This pragma is identical in effect to pragma Common_Object.


pragma Pure_Function
Syntax:
          pragma Pure_Function ([Entity =>] function_LOCAL_NAME);
     

This pragma appears in the same declarative part as a function declaration (or a set of function declarations if more than one overloaded declaration exists, in which case the pragma applies to all entities). If specifies that the function Entity is to be considered pure for the purposes of code generation. This means that the compiler can assume that there are no side effects, and in particular that two calls with identical arguments produce the same result. It also means that the function can be used in an address clause.

Note that, quite deliberately, there are no static checks to try to ensure that this promise is met, so Pure_Function can be used with functions that are conceptually pure, even if they do modify global variables. For example, a square root function that is instrumented to count the number of times it is called is still conceptually pure, and can still be optimized, even though it modifies a global variable (the count). Memo functions are another example (where a table of previous calls is kept and consulted to avoid re-computation).

Note: Most functions in a Pure package are automatically pure, and there is no need to use pragma Pure_Function for such functions. An exception is any function that has at least one formal of type System.Address or a type derived from it. Such functions are not considered pure by default, since the compiler assumes that the Address parameter may be functioning as a pointer and that the referenced data may change even if the address value does not. The use of pragma Pure_Function for such a function will override this default assumption, and cause the compiler to treat such a function as pure.

Note: If pragma Pure_Function is applied to a renamed function, it applies to the underlying renamed function. This can be used to disambiguate cases of overloading where some but not all functions in a set of overloaded functions are to be designated as pure.


pragma Ravenscar
Syntax:
          pragma Ravenscar
     

A configuration pragma that establishes the following set of restrictions:

No_Abort_Statements
[RM D.7] There are no abort_statements, and there are no calls to Task_Identification.Abort_Task.
No_Select_Statements
There are no select_statements.
No_Task_Hierarchy
[RM D.7] All (non-environment) tasks depend directly on the environment task of the partition.
No_Task_Allocators
[RM D.7] There are no allocators for task types or types containing task subcomponents.
No_Dynamic_Priorities
[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities.
No_Terminate_Alternatives
[RM D.7] There are no selective_accepts with terminate_alternatives
No_Dynamic_Interrupts
There are no semantic dependencies on Ada.Interrupts.
No_Protected_Type_Allocators
There are no allocators for protected types or types containing protected subcomponents.
No_Local_Protected_Objects
Protected objects and access types that designate such objects shall be declared only at library level.
No_Requeue
Requeue statements are not allowed.
No_Calendar
There are no semantic dependencies on the package Ada.Calendar.
No_Relative_Delay
There are no delay_relative_statements.
No_Task_Attributes
There are no semantic dependencies on the Ada.Task_Attributes package and there are no references to the attributes Callable and Terminated [RM 9.9].
Static_Storage_Size
The expression for pragma Storage_Size is static.
Boolean_Entry_Barriers
Entry barrier condition expressions shall be boolean objects which are declared in the protected type which contains the entry.
Max_Asynchronous_Select_Nesting = 0
[RM D.7] Specifies the maximum dynamic nesting level of asynchronous_selects. A value of zero prevents the use of any asynchronous_select.
Max_Task_Entries = 0
[RM D.7] Specifies the maximum number of entries per task. The bounds of every entry family of a task unit shall be static, or shall be defined by a discriminant of a subtype whose corresponding bound is static. A value of zero indicates that no rendezvous are possible. For the Ravenscar pragma, the value of Max_Task_Entries is always 0 (zero).
Max_Protected_Entries = 1
[RM D.7] Specifies the maximum number of entries per protected type. The bounds of every entry family of a protected unit shall be static, or shall be defined by a discriminant of a subtype whose corresponding bound is static. For the Ravenscar pragma the value of Max_Protected_Entries is always 1.
Max_Select_Alternatives = 0
[RM D.7] Specifies the maximum number of alternatives in a selective_accept. For the Ravenscar pragma the value if always 0.
No_Task_Termination
Tasks which terminate are erroneous.
No_Entry_Queue
No task can be queued on a protected entry. Note that this restrictions is checked at run time. The violation of this restriction generates a Program_Error exception.

This set of restrictions corresponds to the definition of the “Ravenscar Profile” for limited tasking, devised and published by the International Real-Time Ada Workshop, 1997.

The above set is a superset of the restrictions provided by pragma Restricted_Run_Time, it includes six additional restrictions (Boolean_Entry_Barriers, No_Select_Statements, No_Calendar, Static_Storage_Size, No_Relative_Delay and No_Task_Termination). This means that pragma Ravenscar, like the pragma Restricted_Run_Time, automatically causes the use of a simplified, more efficient version of the tasking run-time system.


pragma Restricted_Run_Time
Syntax:
          pragma Restricted_Run_Time
     

A configuration pragma that establishes the following set of restrictions:

This set of restrictions causes the automatic selection of a simplified version of the run time that provides improved performance for the limited set of tasking functionality permitted by this set of restrictions.


pragma Share_Generic
Syntax:
          pragma Share_Generic (NAME {, NAME});
     

This pragma is recognized for compatibility with other Ada compilers but is ignored by GNAT. GNAT does not provide the capability for sharing of generic code. All generic instantiations result in making an inlined copy of the template with appropriate substitutions.


pragma Source_File_Name
Syntax:
          pragma Source_File_Name (
            [Unit_Name   =>] unit_NAME,
            Spec_File_Name =>  STRING_LITERAL);
          
          pragma Source_File_Name (
            [Unit_Name   =>] unit_NAME,
            Body_File_Name =>  STRING_LITERAL);
     

Use this 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. unit_name is mapped to file_name_literal. The identifier for the second argument is required, and indicates whether this is the file name for the spec or for the body.

Another form of the Source_File_Name pragma allows the specification of patterns defining alternative file naming schemes to apply to all files.

          pragma Source_File_Name
            (Spec_File_Name => STRING_LITERAL
             [,Casing => CASING_SPEC]
             [,Dot_Replacement => STRING_LITERAL]);
          
          pragma Source_File_Name
            (Body_File_Name => STRING_LITERAL
             [,Casing => CASING_SPEC]
             [,Dot_Replacement => STRING_LITERAL]);
          
          pragma Source_File_Name
            (Subunit_File_Name => STRING_LITERAL
             [,Casing => CASING_SPEC]
             [,Dot_Replacement => STRING_LITERAL]);
          
          CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
     

The first argument is a pattern that contains a single asterisk indicating the point at which the unit name is to be inserted in the pattern string to form the file name. The second argument is optional. If present it specifies the casing of the unit name in the resulting file name string. The default is lower case. Finally the third argument allows for systematic replacement of any dots in the unit name by the specified string literal.

For more details on the use of the Source_File_Name pragma, see the sections “Using Other File Names” and “Alternative File Naming Schemes” in the GNAT User's Guide.


pragma Source_Reference
Syntax:
          pragma Source_Reference (INTEGER_LITERAL,
                                   STRING_LITERAL);
     

This pragma must appear as the first line of a source file. integer_literal is the logical line number of the line following the pragma line (for use in error messages and debugging information). string_literal 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.

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 Stream_Convert
Syntax:
          pragma Stream_Convert (
            [Entity =>] type_LOCAL_NAME,
            [Read   =>] function_NAME,
            [Write  =>] function NAME);
     

This pragma provides an efficient way of providing stream functions for types defined in packages. Not only is it simpler to use than declaring the necessary functions with attribute representation clauses, but more significantly, it allows the declaration to made in such a way that the stream packages are not loaded unless they are needed. The use of the Stream_Convert pragma adds no overhead at all, unless the stream attributes are actually used on the designated type.

The first argument specifies the type for which stream functions are provided. The second parameter provides a function used to read values of this type. It must name a function whose argument type may be any subtype, and whose returned type must be the type given as the first argument to the pragma.

The meaning of the Read parameter is that if a stream attribute directly or indirectly specifies reading of the type given as the first parameter, then a value of the type given as the argument to the Read function is read from the stream, and then the Read function is used to convert this to the required target type.

Similarly the Write parameter specifies how to treat write attributes that directly or indirectly apply to the type given as the first parameter. It must have an input parameter of the type specified by the first parameter, and the return type must be the same as the input type of the Read function. The effect is to first call the Write function to convert to the given stream type, and then write the result type to the stream.

The Read and Write functions must not be overloaded subprograms. If necessary renamings can be supplied to meet this requirement. The usage of this attribute is best illustrated by a simple example, taken from the GNAT implementation of package Ada.Strings.Unbounded:

          function To_Unbounded (S : String)
                     return Unbounded_String
            renames To_Unbounded_String;
          
          pragma Stream_Convert
            (Unbounded_String, To_Unbounded, To_String);
     

The specifications of the referenced functions, as given in the Ada 95 Reference Manual are:

          function To_Unbounded_String (Source : String)
            return Unbounded_String;
          
          function To_String (Source : Unbounded_String)
            return String;
     

The effect is that if the value of an unbounded string is written to a stream, then the representation of the item in the stream is in the same format used for Standard.String, and this same representation is expected when a value of this type is read from the stream.


pragma Style_Checks
Syntax:
          pragma Style_Checks (string_LITERAL | ALL_CHECKS |
                               On | Off [, LOCAL_NAME]);
     

This pragma is used in conjunction with compiler switches to control the built in style checking provided by GNAT. The compiler switches, if set provide an initial setting for the switches, and this pragma may be used to modify these settings, or the settings may be provided entirely by the use of the pragma. This pragma can be used anywhere that a pragma is legal, including use as a configuration pragma (including use in the gnat.adc file).

The form with a string literal specifies which style options are to be activated. These are additive, so they apply in addition to any previously set style check options. The codes for the options are the same as those used in the -gnaty switch to gcc or gnatmake. For example the following two methods can be used to enable layout checking:

          pragma Style_Checks ("l");
          gcc -c -gnatyl ...
     

The form ALL_CHECKS activates all standard checks (its use is equivalent to the use of the gnaty switch with no options. See GNAT User's Guide for details.

The forms with Off and On can be used to temporarily disable style checks as shown in the following example:

          pragma Style_Checks ("k"); -- requires keywords in lower case
          pragma Style_Checks (Off); -- turn off style checks
          NULL;                      -- this will not generate an error message
          pragma Style_Checks (On);  -- turn style checks back on
          NULL;                      -- this will generate an error message
     

Finally the two argument form is allowed only if the first argument is On or Off. The effect is to turn of semantic style checks for the specified entity, as shown in the following example:

          pragma Style_Checks ("r"); -- require consistency of identifier casing
          Arg : Integer;
          Rf1 : Integer := ARG;      -- incorrect, wrong case
          pragma Style_Checks (Off, Arg);
          Rf2 : Integer := ARG;      -- OK, no error
     


pragma Subtitle
Syntax:
          pragma Subtitle ([Subtitle =>] STRING_LITERAL);
     

This pragma is recognized for compatibility with other Ada compilers but is ignored by GNAT.


pragma Suppress_All
Syntax:
          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 83 usage. The use of pragma Suppress (All_Checks) as a normal configuration pragma is the preferred usage in GNAT.


pragma Suppress_Initialization
Syntax:
          pragma Suppress_Initialization ([Entity =>] type_Name);
     

This pragma suppresses any implicit or explicit initialization associated with the given type name for all variables of this type.


pragma Task_Info
Syntax
          pragma 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. The Task_Info pragma provides system dependent control over aspect of tasking implementation, for example, the ability to map tasks to specific processors. For details on the facilities available for the version of GNAT that you are using, see the documentation in the specification of package System.Task_Info in the runtime library.


pragma Task_Name
Syntax
          pragma Task_Name (string_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 String, and provides a name to be used for the task instance when the task is created. Note that this expression is not required to be static, and in particular, it can contain references to task discriminants. This facility can be used to provide different names for different tasks as they are created, as illustrated in the example below.

The task name is recorded internally in the run-time structures and is accessible to tools like the debugger. In addition the routine Ada.Task_Identification.Image will return this string, with a unique task address appended.

          --  Example of the use of pragma Task_Name
          
          with Ada.Task_Identification;
          use Ada.Task_Identification;
          with Text_IO; use Text_IO;
          procedure t3 is
          
             type Astring is access String;
          
             task type Task_Typ (Name : access String) is
                pragma Task_Name (Name.all);
             end Task_Typ;
          
             task body Task_Typ is
                Nam : constant String := Image (Current_Task);
             begin
                Put_Line ("-->" & Nam (1 .. 14) & "<--");
             end Task_Typ;
          
             type Ptr_Task is access Task_Typ;
             Task_Var : Ptr_Task;
          
          begin
             Task_Var :=
               new Task_Typ (new String'("This is task 1"));
             Task_Var :=
               new Task_Typ (new String'("This is task 2"));
          end;
     


pragma Task_Storage
Syntax:
          pragma Task_Storage
            [Task_Type =>] LOCAL_NAME,
            [Top_Guard =>] static_integer_EXPRESSION);
     

This pragma specifies the length of the guard area for tasks. The guard area is an additional storage area allocated to a task. A value of zero means that either no guard area is created or a minimal guard area is created, depending on the target. This pragma can appear anywhere a Storage_Size attribute definition clause is allowed for a task type.


pragma Time_Slice
Syntax:
          pragma Time_Slice (static_duration_EXPRESSION);
     

For implementations of GNAT on operating systems where it is possible to supply a time slice value, this pragma may be used for this purpose. It is ignored if it is used in a system that does not allow this control, or if it appears in other than the main program unit. Note that the effect of this pragma is identical to the effect of the DEC Ada 83 pragma of the same name when operating under OpenVMS systems.


pragma Title
Syntax:
          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 used in DEC Ada 83 implementations to provide a title and/or subtitle for the program listing. The program listing generated by GNAT does not have titles or subtitles.

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
Syntax:
          pragma Unchecked_Union (first_subtype_LOCAL_NAME)
     

This pragma is used to declare that the specified type should be represented in a manner 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:

In addition, given a type that meets the above requirements, the following restrictions apply to its use throughout the program:

Equality and inequality operations on unchecked_unions are not available, since there is no discriminant to compare and 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 Suppress (Discriminant_Check) applies implicitly to the type and the default convention is C


pragma Unimplemented_Unit
Syntax:
          pragma Unimplemented_Unit;
     

If this pragma occurs in a unit that is processed by the compiler, GNAT aborts with the message `xxx not implemented', where xxx is the name of the current compilation unit. This pragma is intended to allow the compiler to handle unimplemented library units in a clean manner.

The abort only happens if code is being generated. Thus you can use specs of unimplemented packages in syntax or semantic checking mode.


pragma Unreferenced
Syntax:
          pragma Unreferenced (local_Name {, local_Name});
     

This pragma signals that the entities whose names are listed are deliberately not referenced. This suppresses warnings about the entities being unreferenced, and in addition a warning will be generated if one of these entities is in fact referenced.

This is particularly useful for clearly signalling that a particular parameter is not referenced in some particular subprogram implementation and that this is deliberate. It can also be useful in the case of objects declared only for their initialization or finalization side effects.

If local_Name identifies more than one matching homonym in the current scope, then the entity most recently declared is the one to which the pragma applies.


pragma Unreserve_All_Interrupts
Syntax:
          pragma Unreserve_All_Interrupts;
     

Normally certain interrupts are reserved to the implementation. Any attempt to attach an interrupt causes Program_Error to be raised, as described in RM C.3.2(22). A typical example is the SIGINT interrupt used in many systems for an Ctrl-C interrupt. Normally this interrupt is reserved to the implementation, so that Ctrl-C can be used to interrupt execution.

If the pragma Unreserve_All_Interrupts appears anywhere in any unit in a program, then all such interrupts are unreserved. This allows the program to handle these interrupts, but disables their standard functions. For example, if this pragma is used, then pressing Ctrl-C will not automatically interrupt execution. However, a program can then handle the SIGINT interrupt as it chooses.

For a full list of the interrupts handled in a specific implementation, see the source code for the specification of Ada.Interrupts.Names in file a-intnam.ads. This is a target dependent file that contains the list of interrupts recognized for a given target. The documentation in this file also specifies what interrupts are affected by the use of the Unreserve_All_Interrupts pragma.


pragma Unsuppress
Syntax:
          pragma Unsuppress (IDENTIFIER [, [On =>] NAME]);
     

This pragma undoes the effect of a previous pragma Suppress. If there is no corresponding pragma Suppress in effect, 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 Use_VADS_Size
Syntax:
          pragma Use_VADS_Size;
     

This is a configuration pragma. In a unit to which it applies, any use of the 'Size attribute is automatically interpreted as a use of the 'VADS_Size attribute. Note that this may result in incorrect semantic processing of valid Ada 95 programs. This is intended to aid in the handling of legacy code which depends on the interpretation of Size as implemented in the VADS compiler. See description of the VADS_Size attribute for further details.


pragma Validity_Checks
Syntax:
          pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off);
     

This pragma is used in conjunction with compiler switches to control the built in validity checking provided by GNAT. The compiler switches, if set provide an initial setting for the switches, and this pragma may be used to modify these settings, or the settings may be provided entirely by the use of the pragma. This pragma can be used anywhere that a pragma is legal, including use as a configuration pragma (including use in the gnat.adc file).

The form with a string literal specifies which validity options are to be activated. The validity checks are first set to include only the default reference manual settings, and then a string of letters in the string specifies the exact set of options required. The form of this string is exactly as described for the -gnatVx compiler switch (see the GNAT users guide for details). For example the following two methods can be used to enable validity checking for mode in and in out subprogram parameters:

          pragma Validity_Checks ("im");
          gcc -c -gnatVim ...
     

The form ALL_CHECKS activates all standard checks (its use is equivalent to the use of the gnatva switch.

The forms with Off and On can be used to temporarily disable validity checks as shown in the following example:

          pragma Validity_Checks ("c"); -- validity checks for copies
          pragma Validity_Checks (Off); -- turn off validity checks
          A := B;                       -- B will not be validity checked
          pragma Validity_Checks (On);  -- turn validity checks back on
          A := C;                       -- C will be validity checked
     


pragma Volatile
Syntax:
          pragma Volatile (local_NAME)
     

This pragma is defined by the Ada 95 Reference Manual, and the GNAT implementation is fully conformant with this definition. The reason it is mentioned in this section is that a pragma of the same name was supplied in some Ada 83 compilers, including DEC Ada 83. The Ada 95 implementation of pragma Volatile is upwards compatible with the implementation in Dec Ada 83.


pragma Warnings
Syntax:
          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 the local_name parameter is present, warnings are suppressed for the specified entity. 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).


pragma Weak_External
Syntax:
          pragma Weak_External ([Entity =>] LOCAL_NAME);
     

This pragma specifies that the given entity should be marked as a weak external (one that does not have to be resolved) for the linker. For further details, consult the GCC manual.