dwww Home | Show directory contents | Find package


                                   Annex B
                                 (normative)

                        Interface to Other Languages


1   This Annex describes features for writing mixed-language programs. General
interface support is presented first; then specific support for C, COBOL, and
Fortran is defined, in terms of language interface packages for each of these
languages.

1.a         Ramification: This Annex is not a "Specialized Needs" annex. Every
            implementation must support all nonoptional features defined here
            (mainly the package Interfaces).


                         Language Design Principles

1.b         Ada should have strong support for mixed-language programming.


                         Implementation Requirements

2/3 {AI05-0229-1} {AI05-0262-1} {AI05-0299-1} Support for interfacing to any
foreign language is optional. However, an implementation shall not provide any
optional aspect, attribute, library unit, or pragma having the same name as an
aspect, attribute, library unit, or pragma (respectively) specified in the
subclauses of this Annex unless the provided construct is either as specified
in those subclauses or is more limited in capability than that required by
those subclauses. A program that attempts to use an unsupported capability of
this Annex shall either be identified by the implementation before run time or
shall raise an exception at run time.

2.a/3       Discussion: The intent is that the same rules apply for the
            optional parts of language interfacing as apply for Specialized
            Needs Annexes. See 1.1.3 for a discussion of the purpose of these
            rules.


                            Extensions to Ada 83

2.b         Much of the functionality in this Annex is new to Ada 95.


                         Wording Changes from Ada 83

2.c         This Annex contains what used to be RM83-13.8.


                        Wording Changes from Ada 2005

2.d/3       {AI05-0262-1} Moved the clarification that interfacing to foreign
            languages is optional and has the same restrictions as a
            Specialized Needs Annex here.


B.1 Interfacing Aspects


0.1/3 {AI05-0229-1} An interfacing aspect is a representation aspect that is
one of the aspects Import, Export, Link_Name, External_Name, or Convention.

1/3 {AI05-0229-1} {AI05-0269-1} Specifying the Import aspect to have the value
True is used to import an entity defined in a foreign language into an Ada
program, thus allowing a foreign-language subprogram to be called from Ada, or
a foreign-language variable to be accessed from Ada. In contrast, specifying
the Export aspect to have the value True is used to export an Ada entity to a
foreign language, thus allowing an Ada subprogram to be called from a foreign
language, or an Ada object to be accessed from a foreign language. The Import
and Export aspects are intended primarily for objects and subprograms,
although implementations are allowed to support other entities. The Link_Name
and External_Name aspects are used to specify the link name and external name,
respectively, to be used to identify imported or exported entities in the
external environment.

1.a/3       Aspect Description for Import: Entity is imported from another
            language.

1.b/3       Aspect Description for Export: Entity is exported to another
            language.

1.c/3       Aspect Description for External_Name: Name used to identify an
            imported or exported entity.

1.d/3       Aspect Description for Link_Name: Linker symbol used to identify
            an imported or exported entity.

2/3 {AI05-0229-1} The Convention aspect is used to indicate that an Ada entity
should use the conventions of another language. It is intended primarily for
types and "callback" subprograms. For example, "with Convention => Fortran" on
the declaration of an array type Matrix implies that Matrix should be
represented according to the conventions of the supported Fortran
implementation, namely column-major order.

2.a/3       Aspect Description for Convention: Calling convention or other
            convention used for interfacing to other languages.

3   A pragma Linker_Options is used to specify the system linker parameters
needed when a given compilation unit is included in a partition.


                                   Syntax

4/3     {AI05-0229-1} The form of a pragma Linker_Options is as follows:

        Paragraphs 5 through 7 were moved to Annex J, "Obsolescent Features
        ".

8         pragma Linker_Options(string_expression);

9       A pragma Linker_Options is allowed only at the place of a
        declarative_item.

9.1/3   This paragraph was deleted.{8652/0058} {AI95-00036-01} {AI05-0229-1}


                            Name Resolution Rules

9.2/3 {AI05-0229-1} The Import and Export aspects are of type Boolean.

10/3 {AI05-0229-1} The Link_Name and External_Name aspects are of type String.

10.a/3      Ramification: There is no language-defined support for external or
            link names of type Wide_String, or of other string types.
            Implementations may, of course, have additional aspects for that
            purpose. Note that allowing both String and Wide_String in the
            same aspect_definition would cause ambiguities.

10.1/3 {AI05-0229-1} The expected type for the string_expression in pragma
Linker_Options is String.


                               Legality Rules

11/3 {AI05-0229-1} The aspect Convention shall be specified by a
convention_identifier which shall be the name of a convention. The convention names are
implementation defined, except for certain language-defined ones, such as Ada
and Intrinsic, as explained in 6.3.1, "Conformance Rules". [Additional
convention names generally represent the calling conventions of foreign
languages, language implementations, or specific run-time models.] The
convention of a callable entity is its calling convention.

11.a        Implementation defined: Implementation-defined convention names.

11.b        Discussion: We considered representing the convention names using
            an enumeration type declared in System. Then,
            convention_identifier would be changed to convention_name, and we would make
            its expected type be the enumeration type. We didn't do this
            because it seems to introduce extra complexity, and because the
            list of available languages is better represented as the list of
            children of package Interfaces - a more open-ended sort of list.

12  If L is a convention_identifier for a language, then a type T is said to
be compatible with convention L, (alternatively, is said to be an L-compatible
type) if any of the following conditions are met:

13    * T is declared in a language interface package corresponding to L and
        is defined to be L-compatible (see B.3, B.3.1, B.3.2, B.4, B.5),

14/3   * {AI05-0229-1} Convention L has been specified for T, and T is
        eligible for convention L; that is:

14.1/4    * {AI12-0135-1} T is an enumeration type such that all internal
            codes (whether assigned by default or explicitly) are within an
            implementation-defined range that includes at least the range of
            values 0 .. 2**15-1;

15        * T is an array type with either an unconstrained or
            statically-constrained first subtype, and its component type is
            L-compatible,

16        * T is a record type that has no discriminants and that only has
            components with statically-constrained subtypes, and each
            component type is L-compatible,

17/3      * {AI05-0002-1} T is an access-to-object type, its designated type
            is L-compatible, and its designated subtype is not an
            unconstrained array subtype,

18        * T is an access-to-subprogram type, and its designated profile's
            parameter and result types are all L-compatible.

19    * T is derived from an L-compatible type,

20    * The implementation permits T as an L-compatible type.

20.a        Discussion: For example, an implementation might permit Integer as
            a C-compatible type, though the C type to which it corresponds
            might be different in different environments.

21/3 {AI05-0229-1} If the Convention aspect is specified for a type, then the
type shall either be compatible with or eligible for the specified convention.

21.a/3      Ramification: {AI05-0229-1} If a type is derived from an
            L-compatible type, the derived type is by default L-compatible,
            but it is also permitted to specify the Convention aspect for the
            derived type.

21.b/3      {AI05-0229-1} It is permitted to specify the Convention aspect for
            an incomplete type, but in the complete declaration each component
            must be L-compatible.

21.c/3      {AI05-0229-1} If each component of a record type is L-compatible,
            then the record type itself is only L-compatible if it has a
            specified Convention.

22/3 {AI05-0229-1} Notwithstanding any rule to the contrary, a declaration
with a True Import aspect shall not have a completion.

22.a/3      Discussion: {AI05-0229-1} For declarations of deferred constants
            and subprograms, we explicitly mention that no completion is
            allowed when aspect Import is True. For other declarations that
            require completions, we ignore the possibility of the aspect
            Import being True. Nevertheless, if an implementation chooses to
            allow specifying aspect Import to be True for the declaration of a
            task, protected type, incomplete type, private type, etc., it may
            do so, and the normal completion is then not allowed for that
            declaration.

23/3 {AI05-0229-1} An entity with a True Import aspect (or Export aspect) is
said to be imported (respectively, exported). An entity shall not be both
imported and exported.

24  The declaration of an imported object shall not include an explicit
initialization expression. [Default initializations are not performed.]

24.a        Proof: This follows from the "Notwithstanding ..." wording in the
            Dynamics Semantics paragraphs below.

25/3 {AI05-0229-1} The type of an imported or exported object shall be
compatible with the specified Convention aspect, if any.

25.a        Ramification: This implies, for example, that importing an Integer
            object might be illegal, whereas importing an object of type
            Interfaces.C.int would be permitted.

26/3 {AI05-0229-1} For an imported or exported subprogram, the result and
parameter types shall each be compatible with the specified Convention aspect,
if any.

27/3 {AI05-0229-1} The aspect_definition (if any) used to directly specify an
Import, Export, External_Name, or Link_Name aspect shall be a static
expression. The string_expression of a pragma Linker_Options shall be static.
An External_Name or Link_Name aspect shall be specified only for an entity
that is either imported or exported.


                              Static Semantics

Paragraphs 28 and 29 were deleted.

30/3 {AI05-0229-1} The Convention aspect represents the calling convention or
representation convention of the entity. For an access-to-subprogram type, it
represents the calling convention of designated subprograms. In addition:

31/3   * A True Import aspect indicates that the entity is defined externally
        (that is, outside the Ada program). This aspect is never inherited; if
        not directly specified, the Import aspect is False.

32/3   * A True Export aspect indicates that the entity is used externally.
        This aspect is never inherited; if not directly specified, the Export
        aspect is False.

33/3   * For an entity with a True Import or Export aspect, an external name,
        link name, or both may also be specified.

34  An external name is a string value for the name used by a foreign language
program either for an entity that an Ada program imports, or for referring to
an entity that an Ada program exports.

35  A link name is a string value for the name of an exported or imported
entity, based on the conventions of the foreign language's compiler in
interfacing with the system's linker tool.

36  The meaning of link names is implementation defined. If neither a link
name nor the Address attribute of an imported or exported entity is specified,
then a link name is chosen in an implementation-defined manner, based on the
external name if one is specified.

36.a        Implementation defined: The meaning of link names.

36.b        Ramification: For example, an implementation might always prepend
            "_", and then pass it to the system linker.

36.c        Implementation defined: The manner of choosing link names when
            neither the link name nor the address of an imported or exported
            entity is specified.

36.d        Ramification: Normally, this will be the entity's defining name,
            or some simple transformation thereof.

37  Pragma Linker_Options has the effect of passing its string argument as a
parameter to the system linker (if one exists), if the immediately enclosing
compilation unit is included in the partition being linked. The interpretation
of the string argument, and the way in which the string arguments from
multiple Linker_Options pragmas are combined, is implementation defined.

37.a        Implementation defined: The effect of pragma Linker_Options.


                              Dynamic Semantics

38/3 {AI05-0229-1} Notwithstanding what this International Standard says
elsewhere, the elaboration of a declaration with a True Import aspect does not
create the entity. Such an elaboration has no other effect than to allow the
defining name to denote the external entity.

38.a        Ramification: This implies that default initializations are
            skipped. (Explicit initializations are illegal.) For example, an
            imported access object is not initialized to null.

38.b/3      This paragraph was deleted.{AI05-0229-1}

38.c/3      Discussion: {AI05-0229-1} This "notwithstanding" wording is better
            than saying "unless aspect Import is True" on every definition of
            elaboration. It says we recognize the contradiction, and this rule
            takes precedence.


                             Erroneous Execution

38.1/3 {AI95-00320-01} {AI05-0229-1} It is the programmer's responsibility to
ensure that the use of interfacing aspects does not violate Ada semantics;
otherwise, program execution is erroneous.


                            Implementation Advice

39/3 {AI05-0229-1} If an implementation supports Export for a given language,
then it should also allow the main subprogram to be written in that language.
It should support some mechanism for invoking the elaboration of the Ada
library units included in the system, and for invoking the finalization of the
environment task. On typical systems, the recommended mechanism is to provide
two subprograms whose link names are "adainit" and "adafinal". Adainit should
contain the elaboration code for library units. Adafinal should contain the
finalization code. These subprograms should have no effect the second and
subsequent time they are called.

39.a.1/3    Implementation Advice: If Export is supported for a language, the
            main program should be able to be written in that language.
            Subprograms named "adainit" and "adafinal" should be provided for
            elaboration and finalization of the environment task.

39.a        Ramification: For example, if the main subprogram is written in C,
            it can call adainit before the first call to an Ada subprogram,
            and adafinal after the last.

40/3 {AI05-0229-1} {AI05-0269-1} Automatic elaboration of preelaborated
packages should be provided when specifying the Export aspect as True is
supported.

40.a.1/3    Implementation Advice: Automatic elaboration of preelaborated
            packages should be provided when specifying the Export aspect as
            True is supported.

41/4 {AI05-0229-1} {AI12-0135-1} For each supported convention L other than
Intrinsic, an implementation should support specifying the Import and Export
aspects for objects of L-compatible types and for subprograms, and the
Convention aspect for L-eligible types and for subprograms, presuming the
other language has corresponding features. Specifying the Convention aspect
need not be supported for scalar types, other than enumeration types whose
internal codes fall within the range 0 .. 2**15-1.

41.a.1/3    Implementation Advice: For each supported convention L other than
            Intrinsic, specifying the aspects Import and Export should be
            supported for objects of L-compatible types and for subprograms,
            and aspect Convention should be supported for L-eligible types and
            for subprograms.

41.a/3      Reason: {AI05-0229-1} Specifying aspect Convention is not
            necessary for scalar types, since the language interface packages
            declare scalar types corresponding to those provided by the
            respective foreign languages.

41.b/2      Implementation Note: {AI95-00114-01} If an implementation supports
            interfacing to the C++ entities not supported by B.3, it should do
            so via the convention identifier C_Plus_Plus (in additional to any
            C++-implementation-specific ones).

41.c/2      Reason: {AI95-00114-01} The reason for giving the advice about C++
            is to encourage uniformity among implementations, given that the
            name of the language is not syntactically legal as an identifier.

        NOTES

42/3    1  {AI05-0229-1} Implementations may place restrictions on interfacing
        aspects; for example, requiring each exported entity to be declared at
        the library level.

42.a        Proof: Arbitrary restrictions are allowed by 13.1.

42.b        Ramification: Such a restriction might be to disallow them
            altogether. Alternatively, the implementation might allow them
            only for certain kinds of entities, or only for certain
            conventions.

43/3    2  {AI05-0229-1} The Convention aspect in combination with the Import
        aspect indicates the conventions for accessing external entities. It
        is possible that the actual entity is written in assembly language,
        but reflects the conventions of a particular language. For example,
        with Convention => Ada can be used to interface to an assembly
        language routine that obeys the Ada compiler's calling conventions.

44/3    3  {AI05-0229-1} To obtain "call-back" to an Ada subprogram from a
        foreign language environment, the Convention aspect should be
        specified both for the access-to-subprogram type and the specific
        subprogram(s) to which 'Access is applied.

        Paragraphs 45 and 46 were deleted.

47      4  See also 13.8, "Machine Code Insertions".

47.a/3      Ramification: {AI05-0229-1} The Intrinsic convention (see 6.3.1)
            implies that the entity is somehow "built in" to the
            implementation. Thus, it generally does not make sense for users
            to specify Intrinsic along with specifying that the entity is
            imported. The intention is that only implementations will specify
            Intrinsic for an imported entity. The language also defines
            certain subprograms to be Intrinsic.

47.b/3      Discussion: {AI05-0229-1} There are many imaginable interfacing
            aspects that don't make any sense. For example, setting the
            Convention of a protected procedure to Ada is probably wrong.
            Rather than enumerating all such cases, however, we leave it up to
            implementations to decide what is sensible.

48/3    5  {AI05-0229-1} If both External_Name and Link_Name are specified for
        a given entity, then the External_Name is ignored.

49/2    This paragraph was deleted.{AI95-00320-01}


                                  Examples

50/4 {AI12-0080-1} Example of interfacing aspects:

51/3    {AI05-0229-1} {AI05-0269-1} package Fortran_Library is
          function Sqrt (X : Float) return Float
            with Import => True, Convention => Fortran;
          type Matrix is array (Natural range <>, Natural range <>) of Float
            with Convention => Fortran;
          function Invert (M : Matrix) return Matrix
            with Import => True, Convention => Fortran;
        end Fortran_Library;


                            Extensions to Ada 83

51.a        Interfacing pragmas are new to Ada 95. Pragma Import replaces Ada
            83's pragma Interface. Existing implementations can continue to
            support pragma Interface for upward compatibility.


                         Wording Changes from Ada 95

51.b/2      {8652/0058} {AI95-00036-01} Corrigendum: Clarified that pragmas
            Import and Export work like a subprogram call; parameters cannot
            be omitted unless named notation is used. (Reordering is still not
            permitted, however.)

51.c/2      {AI95-00320-01} Added wording to say all bets are off if foreign
            code doesn't follow the semantics promised by the Ada
            specifications.


                       Incompatibilities With Ada 2005

51.d/3      {AI05-0002-1} Correction: Access types that designate
            unconstrained arrays are no longer defined to be L-compatible.
            Such access-to-arrays require bounds information, which is likely
            to be incompatible with a foreign language. The change will allow
            (but not require) compilers to reject bad uses, which probably
            will not work anyway. Note that implementations can still support
            any type that it wants as L-compatible; such uses will not be
            portable, however. As such, there should be little existing code
            that will be impacted (compilers probably already rejected cases
            that could not be translated, whether or not the language allowed
            doing so formally).


                           Extensions to Ada 2005

51.e/3      {AI05-0229-1} Aspects Convention, Import, Export, Link_Name, and
            External_Name are new; pragmas Convention, Import, and Export are
            now obsolescent.


                           Extensions to Ada 2012

51.f/4      {AI12-0135-1} Corrigendum: Added a suggestion that convention be
            supported for enumeration types. This will make the use of
            enumeration types portable for implementations that support
            interfacing to a particular language.


B.2 The Package Interfaces


1   Package Interfaces is the parent of several library packages that declare
types and other entities useful for interfacing to foreign languages. It also
contains some implementation-defined types that are useful across more than
one language (in particular for interfacing to assembly language).

1.a         Implementation defined: The contents of the visible part of
            package Interfaces and its language-defined descendants.


                              Static Semantics

2   The library package Interfaces has the following skeletal declaration:

3       
        package Interfaces is
           pragma Pure(Interfaces);

4          type Integer_n is range -2**(n-1) .. 2**(n-1) - 1;  --2's complement

5          type Unsigned_n is mod 2**n;

6          function Shift_Left  (Value : Unsigned_n; Amount : Natural)
              return Unsigned_n;
           function Shift_Right (Value : Unsigned_n; Amount : Natural)
              return Unsigned_n;
           function Shift_Right_Arithmetic (Value : Unsigned_n; Amount : Natural)
              return Unsigned_n;
           function Rotate_Left  (Value : Unsigned_n; Amount : Natural)
              return Unsigned_n;
           function Rotate_Right (Value : Unsigned_n; Amount : Natural)
              return Unsigned_n;
           ...
        end Interfaces;


                         Implementation Requirements

7   An implementation shall provide the following declarations in the visible
part of package Interfaces:

8     * Signed and modular integer types of n bits, if supported by the target
        architecture, for each n that is at least the size of a storage
        element and that is a factor of the word size. The names of these
        types are of the form Integer_n for the signed types, and Unsigned_n
        for the modular types;

8.a         Ramification: For example, for a typical 32-bit machine the
            corresponding types might be Integer_8, Unsigned_8, Integer_16,
            Unsigned_16, Integer_32, and Unsigned_32.

8.b         The wording above implies, for example, that Integer_16'Size =
            Unsigned_16'Size = 16. Unchecked conversions between same-Sized
            types will work as expected.

9     * For each such modular type in Interfaces, shifting and rotating
        subprograms as specified in the declaration of Interfaces above. These
        subprograms are Intrinsic. They operate on a bit-by-bit basis, using
        the binary representation of the value of the operands to yield a
        binary representation for the result. The Amount parameter gives the
        number of bits by which to shift or rotate. For shifting, zero bits
        are shifted in, except in the case of Shift_Right_Arithmetic, where
        one bits are shifted in if Value is at least half the modulus.

9.a         Reason: We considered making shifting and rotating be primitive
            operations of all modular types. However, it is a design principle
            of Ada that all predefined operations should be operators (not
            functions named by identifiers). (Note that an early version of
            Ada had "abs" as an identifier, but it was changed to a reserved
            word operator before standardization of Ada 83.) This is important
            because the implicit declarations would hide nonoverloadable
            declarations with the same name, whereas operators are always
            overloadable. Therefore, we would have had to make shift and
            rotate into reserved words, which would have been upward
            incompatible, or else invent new operator symbols, which seemed
            like too much mechanism.

10    * Floating point types corresponding to each floating point format fully
        supported by the hardware.

10.a        Implementation Note: The names for these floating point types are
            not specified. However, if IEEE arithmetic is supported, then the
            names should be IEEE_Float_32 and IEEE_Float_64 for single and
            double precision, respectively.


                         Implementation Permissions

11  An implementation may provide implementation-defined library units that
are children of Interfaces, and may add declarations to the visible part of
Interfaces in addition to the ones defined above.

11.a/2      Implementation defined: Implementation-defined children of package
            Interfaces.

11.1/3 {AI95-00204-01} {AI05-0229-1} A child package of package Interfaces
with the name of a convention may be provided independently of whether the
convention is supported by the Convention aspect and vice versa. Such a child
package should contain any declarations that would be useful for interfacing
to the language (implementation) represented by the convention. Any
declarations useful for interfacing to any language on the given hardware
architecture should be provided directly in Interfaces.

11.b/2      Ramification: For example, package Interfaces.XYZ_Pascal might
            contain declarations of types that match the data types provided
            by the XYZ implementation of Pascal, so that it will be more
            convenient to pass parameters to a subprogram whose convention is
            XYZ_Pascal.


                            Implementation Advice

12/2 This paragraph was deleted.{AI95-00204-01}

12.a/2      This paragraph was deleted.

13/3 {AI05-0299-1} An implementation supporting an interface to C, COBOL, or
Fortran should provide the corresponding package or packages described in the
following subclauses.

13.a.1/2    Implementation Advice: If an interface to C, COBOL, or Fortran is
            provided, the corresponding package or packages described in
            Annex B, "Interface to Other Languages" should also be provided.

13.a        Implementation Note: The intention is that an implementation might
            support several implementations of the foreign language:
            Interfaces.This_Fortran and Interfaces.That_Fortran might both
            exist. The "default" implementation, overridable by the user,
            should be declared as a renaming:

13.b            package Interfaces.Fortran renames Interfaces.This_Fortran;


                         Wording Changes from Ada 95

13.c/2      {AI95-00204-01} Clarified that interfacing to foreign languages is
            optional and has the same restrictions as a Specialized Needs
            Annex.


                        Wording Changes from Ada 2005

13.d/3      {AI05-0262-1} Move the restrictions on implementations of optional
            features to the start of this Annex.


B.3 Interfacing with C and C++


1/4 {8652/0059} {AI95-00131-01} {AI95-00376-01} {AI05-0229-1} {AI12-0028-1}
The facilities relevant to interfacing with the C language and the
corresponding subset of the C++ language are the package Interfaces.C and its
children, and support for specifying the Convention aspect with
convention_identifiers C, C_Pass_By_Copy, and any of the C_Variadic_n conventions
described below.

2/3 {AI95-00376-01} {AI95-0262-1} {AI95-0299-1} The package Interfaces.C
contains the basic types, constants, and subprograms that allow an Ada program
to pass scalars and strings to C and C++ functions. When this subclause
mentions a C entity, the reference also applies to the corresponding entity in
C++.


                              Static Semantics

3   The library package Interfaces.C has the following declaration:

4       package Interfaces.C is
           pragma Pure(C);

5          -- Declarations based on C's <limits.h>

6          CHAR_BIT  : constant := implementation-defined;  -- typically 8
           SCHAR_MIN : constant := implementation-defined;  -- typically -128
           SCHAR_MAX : constant := implementation-defined;  -- typically 127
           UCHAR_MAX : constant := implementation-defined;  -- typically 255

7          -- Signed and Unsigned Integers
           type int   is range implementation-defined;
           type short is range implementation-defined;
           type long  is range implementation-defined;

8          type signed_char is range SCHAR_MIN .. SCHAR_MAX;
           for signed_char'Size use CHAR_BIT;

9          type unsigned       is mod implementation-defined;
           type unsigned_short is mod implementation-defined;
           type unsigned_long  is mod implementation-defined;

10         type unsigned_char is mod (UCHAR_MAX+1);
           for unsigned_char'Size use CHAR_BIT;

11         subtype plain_char is implementation-defined;

12         type ptrdiff_t is range implementation-defined;

13         type size_t is mod implementation-defined;

14         -- Floating Point

15         type C_float     is digits implementation-defined;

16         type double      is digits implementation-defined;

17         type long_double is digits implementation-defined;

18         -- Characters and Strings 

19         type char is <implementation-defined character type>;

20/1    {8652/0060} {AI95-00037-01}    nul
         : constant char := implementation-defined;

21         function To_C   (Item : in Character) return char;

22         function To_Ada (Item : in char) return Character;

23/3    {AI05-0229-1} {AI05-0269-1}    type char_array
         is array (size_t range <>) of aliased char
              with Pack;
           for char_array'Component_Size use CHAR_BIT;

24         function Is_Nul_Terminated (Item : in char_array) return Boolean;

25         function To_C   (Item       : in String;
                            Append_Nul : in Boolean := True)
              return char_array;

26         function To_Ada (Item     : in char_array;
                            Trim_Nul : in Boolean := True)
              return String;

27         procedure To_C (Item       : in  String;
                           Target     : out char_array;
                           Count      : out size_t;
                           Append_Nul : in  Boolean := True);

28         procedure To_Ada (Item     : in  char_array;
                             Target   : out String;
                             Count    : out Natural;
                             Trim_Nul : in  Boolean := True);

29         -- Wide Character and Wide String

30/1    {8652/0060} {AI95-00037-01}    type wchar_t
         is <implementation-defined character type>;

31/1    {8652/0060} {AI95-00037-01}    wide_nul
         : constant wchar_t := implementation-defined;

32         function To_C   (Item : in Wide_Character) return wchar_t;
           function To_Ada (Item : in wchar_t       ) return Wide_Character;

33/3    {AI05-0229-1}    type wchar_array
         is array (size_t range <>) of aliased wchar_t
              with Pack;

34/3    This paragraph was deleted.{AI05-0229-1}

35         function Is_Nul_Terminated (Item : in wchar_array) return Boolean;

36         function To_C   (Item       : in Wide_String;
                            Append_Nul : in Boolean := True)
              return wchar_array;

37         function To_Ada (Item     : in wchar_array;
                            Trim_Nul : in Boolean := True)
              return Wide_String;

38         procedure To_C (Item       : in  Wide_String;
                           Target     : out wchar_array;
                           Count      : out size_t;
                           Append_Nul : in  Boolean := True);

39         procedure To_Ada (Item     : in  wchar_array;
                             Target   : out Wide_String;
                             Count    : out Natural;
                             Trim_Nul : in  Boolean := True);

39.1/2  {AI95-00285-01}
           -- ISO/IEC 10646:2003 compatible types defined by ISO/IEC TR 19769:2004.

39.2/2  {AI95-00285-01}    type char16_t
         is <implementation-defined character type>;

39.3/2     char16_nul : constant char16_t := implementation-defined;

39.4/2     function To_C (Item : in Wide_Character) return char16_t;
           function To_Ada (Item : in char16_t) return Wide_Character;

39.5/3  {AI05-0229-1}    type char16_array
         is array (size_t range <>) of aliased char16_t
              with Pack;

39.6/3  This paragraph was deleted.{AI05-0229-1}

39.7/2     function Is_Nul_Terminated (Item : in char16_array) return Boolean;
           function To_C (Item       : in Wide_String;
                          Append_Nul : in Boolean := True)
              return char16_array;

39.8/2     function To_Ada (Item     : in char16_array;
                            Trim_Nul : in Boolean := True)
              return Wide_String;

39.9/2     procedure To_C (Item       : in  Wide_String;
                           Target     : out char16_array;
                           Count      : out size_t;
                           Append_Nul : in  Boolean := True);

39.10/2    procedure To_Ada (Item     : in  char16_array;
                             Target   : out Wide_String;
                             Count    : out Natural;
                             Trim_Nul : in  Boolean := True);

39.11/2 {AI95-00285-01}    type char32_t
         is <implementation-defined character type>;

39.12/2    char32_nul : constant char32_t := implementation-defined;

39.13/2    function To_C (Item : in Wide_Wide_Character) return char32_t;
           function To_Ada (Item : in char32_t) return Wide_Wide_Character;

39.14/3 {AI05-0229-1}    type char32_array
         is array (size_t range <>) of aliased char32_t
              with Pack;

39.15/3 This paragraph was deleted.{AI05-0229-1}

39.16/2    function Is_Nul_Terminated (Item : in char32_array) return Boolean;
           function To_C (Item       : in Wide_Wide_String;
                          Append_Nul : in Boolean := True)
              return char32_array;

39.17/2    function To_Ada (Item     : in char32_array;
                            Trim_Nul : in Boolean := True)
              return Wide_Wide_String;

39.18/2    procedure To_C (Item       : in  Wide_Wide_String;
                           Target     : out char32_array;
                           Count      : out size_t;
                           Append_Nul : in  Boolean := True);

39.19/2    procedure To_Ada (Item     : in  char32_array;
                             Target   : out Wide_Wide_String;
                             Count    : out Natural;
                             Trim_Nul : in  Boolean := True);

40         Terminator_Error : exception;

41      end Interfaces.C;

41.a.1/2    Implementation defined: The definitions of certain types and
            constants in Interfaces.C.

42  Each of the types declared in Interfaces.C is C-compatible.

43/2 {AI95-00285-01} The types int, short, long, unsigned, ptrdiff_t, size_t,
double, char, wchar_t, char16_t, and char32_t correspond respectively to the C
types having the same names. The types signed_char, unsigned_short, unsigned_-
long, unsigned_char, C_float, and long_double correspond respectively to the C
types signed char, unsigned short, unsigned long, unsigned char, float, and
long double.

43.a/2      Discussion: The C types wchar_t and char16_t seem to be the same.
            However, wchar_t has an implementation-defined size, whereas
            char16_t is guaranteed to be an unsigned type of at least 16 bits.
            Also, char16_t and char32_t are encouraged to have UTF-16 and
            UTF-32 representations; that means that they are not directly the
            same as the Ada types, which most likely don't use any UTF
            encoding.

44  The type of the subtype plain_char is either signed_char or unsigned_char,
depending on the C implementation.

45      function To_C   (Item : in Character) return char;
        function To_Ada (Item : in char     ) return Character;

46          The functions To_C and To_Ada map between the Ada type Character
            and the C type char.

46.a.1/1    Implementation Note: {8652/0114} {AI95-00038-01} The To_C and
            To_Ada functions map between corresponding characters, not
            necessarily between characters with the same internal
            representation. Corresponding characters are characters defined by
            the same enumeration literal, if such exist; otherwise, the
            correspondence is unspecified.

46.a.2/1    The following definition is equivalent to the above summary:

46.a.3/1    To_C (Latin_1_Char) = char'Value(Character'Image(Latin_1_Char))
            provided that char'Value does not raise an exception; otherwise
            the result is unspecified.

46.a.4/1    To_Ada (Native_C_Char) = Character'Value(char'Image(Native_C_Char))
            provided that Character'Value does not raise an exception;
            otherwise the result is unspecified.

47      function Is_Nul_Terminated (Item : in char_array) return Boolean;

48          The result of Is_Nul_Terminated is True if Item contains nul, and
            is False otherwise.

49      function To_C   (Item : in String;     Append_Nul : in Boolean := True)
           return char_array;
        
        function To_Ada (Item : in char_array; Trim_Nul   : in Boolean := True)
           return String;

50/2        {AI95-00258-01} The result of To_C is a char_array value of length
            Item'Length (if Append_Nul is False) or Item'Length+1 (if
            Append_Nul is True). The lower bound is 0. For each component
            Item(I), the corresponding component in the result is To_C applied
            to Item(I). The value nul is appended if Append_Nul is True. If
            Append_Nul is False and Item'Length is 0, then To_C propagates
            Constraint_Error.

51          The result of To_Ada is a String whose length is Item'Length (if
            Trim_Nul is False) or the length of the slice of Item preceding
            the first nul (if Trim_Nul is True). The lower bound of the result
            is 1. If Trim_Nul is False, then for each component Item(I) the
            corresponding component in the result is To_Ada applied to
            Item(I). If Trim_Nul is True, then for each component Item(I)
            before the first nul the corresponding component in the result is
            To_Ada applied to Item(I). The function propagates
            Terminator_Error if Trim_Nul is True and Item does not contain nul.

52      procedure To_C (Item       : in  String;
                        Target     : out char_array;
                        Count      : out size_t;
                        Append_Nul : in  Boolean := True);
        
        procedure To_Ada (Item     : in  char_array;
                          Target   : out String;
                          Count    : out Natural;
                          Trim_Nul : in  Boolean := True);

53          For procedure To_C, each element of Item is converted (via the
            To_C function) to a char, which is assigned to the corresponding
            element of Target. If Append_Nul is True, nul is then assigned to
            the next element of Target. In either case, Count is set to the
            number of Target elements assigned. If Target is not long enough,
            Constraint_Error is propagated.

54          For procedure To_Ada, each element of Item (if Trim_Nul is False)
            or each element of Item preceding the first nul (if Trim_Nul is
            True) is converted (via the To_Ada function) to a Character, which
            is assigned to the corresponding element of Target. Count is set
            to the number of Target elements assigned. If Target is not long
            enough, Constraint_Error is propagated. If Trim_Nul is True and
            Item does not contain nul, then Terminator_Error is propagated.

55      function Is_Nul_Terminated (Item : in wchar_array) return Boolean;

56          The result of Is_Nul_Terminated is True if Item contains wide_nul,
            and is False otherwise.

57      function To_C   (Item : in Wide_Character) return wchar_t;
        function To_Ada (Item : in wchar_t       ) return Wide_Character;

58          To_C and To_Ada provide the mappings between the Ada and C wide
            character types.

59      function To_C   (Item       : in Wide_String;
                         Append_Nul : in Boolean := True)
           return wchar_array;
        
        function To_Ada (Item     : in wchar_array;
                         Trim_Nul : in Boolean := True)
           return Wide_String;
        
        procedure To_C (Item       : in  Wide_String;
                        Target     : out wchar_array;
                        Count      : out size_t;
                        Append_Nul : in  Boolean := True);
        
        procedure To_Ada (Item     : in  wchar_array;
                          Target   : out Wide_String;
                          Count    : out Natural;
                          Trim_Nul : in  Boolean := True);

60          The To_C and To_Ada subprograms that convert between Wide_String
            and wchar_array have analogous effects to the To_C and To_Ada
            subprograms that convert between String and char_array, except
            that wide_nul is used instead of nul.

60.1/2  function Is_Nul_Terminated (Item : in char16_array) return Boolean;

60.2/2      {AI95-00285-01} The result of Is_Nul_Terminated is True if Item
            contains char16_nul, and is False otherwise.

60.3/2  function To_C (Item : in Wide_Character) return char16_t;
        function To_Ada (Item : in char16_t ) return Wide_Character;

60.4/2      {AI95-00285-01} To_C and To_Ada provide mappings between the Ada
            and C 16-bit character types.

60.5/2  function To_C (Item       : in Wide_String;
                       Append_Nul : in Boolean := True)
           return char16_array;
        
        function To_Ada (Item     : in char16_array;
                         Trim_Nul : in Boolean := True)
           return Wide_String;
        
        procedure To_C (Item       : in  Wide_String;
                        Target     : out char16_array;
                        Count      : out size_t;
                        Append_Nul : in  Boolean := True);
        
        procedure To_Ada (Item     : in  char16_array;
                          Target   : out Wide_String;
                          Count    : out Natural;
                          Trim_Nul : in  Boolean := True);

60.6/2      {AI95-00285-01} The To_C and To_Ada subprograms that convert
            between Wide_String and char16_array have analogous effects to the
            To_C and To_Ada subprograms that convert between String and
            char_array, except that char16_nul is used instead of nul.

60.7/2  function Is_Nul_Terminated (Item : in char32_array) return Boolean;

60.8/2      {AI95-00285-01} The result of Is_Nul_Terminated is True if Item
            contains char16_nul, and is False otherwise.

60.9/2  function To_C (Item : in Wide_Wide_Character) return char32_t;
        function To_Ada (Item : in char32_t ) return Wide_Wide_Character;

60.10/2     {AI95-00285-01} To_C and To_Ada provide mappings between the Ada
            and C 32-bit character types.

60.11/2 function To_C (Item       : in Wide_Wide_String;
                       Append_Nul : in Boolean := True)
           return char32_array;
        
        function To_Ada (Item     : in char32_array;
                         Trim_Nul : in Boolean := True)
           return Wide_Wide_String;
        
        procedure To_C (Item       : in  Wide_Wide_String;
                        Target     : out char32_array;
                        Count      : out size_t;
                        Append_Nul : in  Boolean := True);
        
        procedure To_Ada (Item     : in  char32_array;
                          Target   : out Wide_Wide_String;
                          Count    : out Natural;
                          Trim_Nul : in  Boolean := True);

60.12/2     {AI95-00285-01} The To_C and To_Ada subprograms that convert
            between Wide_Wide_String and char32_array have analogous effects
            to the To_C and To_Ada subprograms that convert between String and
            char_array, except that char32_nul is used instead of nul.

60.a        Discussion: The Interfaces.C package provides an
            implementation-defined character type, char, designed to model the
            C run-time character set, and mappings between the types char and
            Character.

60.b        One application of the C interface package is to compose a C
            string and pass it to a C function. One way to do this is for the
            programmer to declare an object that will hold the C array, and
            then pass this array to the C function. This is realized via the
            type char_array:

60.c            type char_array is array (size_t range <>) of Char;

60.d        The programmer can declare an Ada String, convert it to a
            char_array, and pass the char_array as actual parameter to the C
            function that is expecting a char *.

60.e        An alternative approach is for the programmer to obtain a C char
            pointer from an Ada String (or from a char_array) by invoking an
            allocation function. The package Interfaces.C.Strings (see below)
            supplies the needed facilities, including a private type chars_ptr
            that corresponds to C's char *, and two allocation functions. To
            avoid storage leakage, a Free procedure releases the storage that
            was allocated by one of these allocate functions.

60.f        It is typical for a C function that deals with strings to adopt
            the convention that the string is delimited by a nul char. The C
            interface packages support this convention. A constant nul of type
            Char is declared, and the function Value(Chars_Ptr) in
            Interfaces.C.Strings returns a char_array up to and including the
            first nul in the array that the chars_ptr points to. The
            Allocate_Chars function allocates an array that is nul terminated.

60.g        Some C functions that deal with strings take an explicit length as
            a parameter, thus allowing strings to be passed that contain nul
            as a data element. Other C functions take an explicit length that
            is an upper bound: the prefix of the string up to the char before
            nul, or the prefix of the given length, is used by the function,
            whichever is shorter. The C Interface packages support calling
            such functions.

60.13/3 {8652/0059} {AI95-00131-01} {AI05-0229-1} The Convention aspect with
convention_identifier C_Pass_By_Copy shall only be specified for a type.

60.14/2 {8652/0059} {AI95-00131-01} {AI95-00216-01} The eligibility rules in
B.1 do not apply to convention C_Pass_By_Copy. Instead, a type T is eligible
for convention C_Pass_By_Copy if T is an unchecked union type or if T is a
record type that has no discriminants and that only has components with
statically constrained subtypes, and each component is C-compatible.

60.15/3 {8652/0059} {AI95-00131-01} {AI05-0264-1} If a type is
C_Pass_By_Copy-compatible, then it is also C-compatible.

60.16/4 {AI12-0028-1} The identifiers C_Variadic_0, C_Variadic_1,
C_Variadic_2, and so on are convention_identifiers. These conventions are said
to be C_Variadic. The convention C_Variadic_n is the calling convention for a
variadic C function taking n fixed parameters and then a variable number of
additional parameters. The C_Variadic_n convention shall only be specified as
the convention aspect for a subprogram, or for an access-to-subprogram type,
having at least n parameters. A type is compatible with a C_Variadic
convention if and only if the type is C-compatible.

60.h/4      To be honest: It is implementation defined what the largest n in
            C_Variadic_n is supported. We don't say this because it
            complicates the wording and it is true for almost any
            convention_identifier (only Ada is required to be supported by the language,
            all others need to be documented in order for programmers to know
            that they are available).


                         Implementation Requirements

61/3 {8652/0059} {AI95-00131-01} {AI05-0229-1} An implementation shall support
specifying aspect Convention with a C convention_identifier for a C-eligible
type (see B.1). An implementation shall support specifying aspect Convention
with a C_Pass_By_Copy convention_identifier for a C_Pass_By_Copy-eligible
type.


                         Implementation Permissions

62  An implementation may provide additional declarations in the C interface
packages.

62.1/3 {AI05-0002-1} {AI05-0229-1} An implementation need not support
specifying the Convention aspect with convention_identifier C in the following
cases:

62.2/3   * {AI05-0248-1} for a subprogram that has a parameter of an
        unconstrained array subtype, unless the Import aspect has the value
        True for the subprogram;

62.3/3   * for a function with an unconstrained array result subtype;

62.4/3   * for an object whose nominal subtype is an unconstrained array
        subtype.

62.a/3      Implementation Note: {AI05-0002-1} These rules ensure that an
            implementation never needs to create bounds for an unconstrained
            array that originates in C (and thus does not have bounds). An
            implementation can do so if it wishes, of course. Note that these
            permissions do not extend to passing an unconstrained array as a
            parameter to a C function; in this case, the bounds can simply be
            dropped and thus support is required.


                            Implementation Advice

62.5/3 {8652/0060} {AI95-00037-01} {AI95-00285-01} The constants nul,
wide_nul, char16_nul, and char32_nul should have a representation of zero.

62.b/2      Implementation Advice: The constants nul, wide_nul, char16_nul,
            and char32_nul in package Interfaces.C should have a
            representation of zero.

63  An implementation should support the following interface correspondences
between Ada and C.

64    * An Ada procedure corresponds to a void-returning C function.

64.a        Discussion: The programmer can also choose an Ada procedure when
            the C function returns an int that is to be discarded.

65    * An Ada function corresponds to a non-void C function.

65.1/4   * {AI12-0135-1} An Ada enumeration type corresponds to a C
        enumeration type with corresponding enumeration literals having the
        same internal codes, provided the internal codes fall within the range
        of the C int type.

66    * An Ada in scalar parameter is passed as a scalar argument to a C
        function.

67    * An Ada in parameter of an access-to-object type with designated type T
        is passed as a t* argument to a C function, where t is the C type
        corresponding to the Ada type T.

68    * An Ada access T parameter, or an Ada out or in out parameter of an
        elementary type T, is passed as a t* argument to a C function, where t
        is the C type corresponding to the Ada type T. In the case of an
        elementary out or in out parameter, a pointer to a temporary copy is
        used to preserve by-copy semantics.

68.1/2   * {8652/0059} {AI95-00131-01} {AI95-00343-01} An Ada parameter of a
        (record) type T of convention C_Pass_By_Copy, of mode in, is passed as
        a t argument to a C function, where t is the C struct corresponding to
        the Ada type T.

69/2   * {8652/0059} {AI95-00131-01} {AI95-00343-01} An Ada parameter of a
        record type T, of any mode, other than an in parameter of a type of
        convention C_Pass_By_Copy, is passed as a t* argument to a C function,
        where t is the C struct corresponding to the Ada type T.

70    * An Ada parameter of an array type with component type T, of any mode,
        is passed as a t* argument to a C function, where t is the C type
        corresponding to the Ada type T.

71    * An Ada parameter of an access-to-subprogram type is passed as a
        pointer to a C function whose prototype corresponds to the designated
        subprogram's specification.

71.1/3   * {AI05-0002-1} An Ada parameter of a private type is passed as
        specified for the full view of the type.

71.2/3   * {AI05-0002-1} The rules of correspondence given above for
        parameters of mode in also apply to the return object of a function.

71.3/3 This paragraph was deleted.{AI95-00337-01} {AI05-0002-1}

71.a/2      Implementation Advice: If C interfacing is supported, the
            interface correspondences between Ada and C should be supported.

        NOTES

72      6  Values of type char_array are not implicitly terminated with nul.
        If a char_array is to be passed as a parameter to an imported C
        function requiring nul termination, it is the programmer's
        responsibility to obtain this effect.

73      7  To obtain the effect of C's sizeof(item_type), where Item_Type is
        the corresponding Ada type, evaluate the expression:
        size_t(Item_Type'Size/CHAR_BIT).

74/2    This paragraph was deleted.{AI95-00216-01}

75/4    8  {AI12-0028-1} A variadic C function can correspond to several Ada
        subprograms, taking various specific numbers and types of parameters.


                                  Examples

76  Example of using the Interfaces.C package:

77      --Calling the C Library Function strcpy
        with Interfaces.C;
        procedure Test is
           package C renames Interfaces.C;
           use type C.char_array;
           -- Call <string.h>strcpy:
           -- C definition of strcpy:  char *strcpy(char *s1, const char *s2);
           --    This function copies the string pointed to by s2 (including the terminating null character)
           --     into the array pointed to by s1. If copying takes place between objects that overlap, 
           --     the behavior is undefined. The strcpy function returns the value of s1.

78/3    {AI05-0229-1}
           -- Note: since the C function's return value is of no interest, the Ada interface is a procedure
           procedure Strcpy (Target : out C.char_array;
                             Source : in  C.char_array)
              with Import => True, Convention => C, External_Name => "strcpy";

79/3    This paragraph was deleted.{AI05-0229-1}

80         Chars1 :  C.char_array(1..20);
           Chars2 :  C.char_array(1..20);

81      begin
           Chars2(1..6) := "qwert" & C.nul;

82         Strcpy(Chars1, Chars2);

83      -- Now Chars1(1..6) = "qwert" & C.Nul

84      end Test;


                        Incompatibilities With Ada 95

84.a/3      {AI95-00285-01} {AI05-0005-1} Types char16_t and char32_t and
            their related types and operations are added to Interfaces.C. If
            Interfaces.C is referenced in a use_clause, and an entity E with
            the same defining_identifier as a new entity in Interfaces.C is
            defined in a package that is also referenced in a use_clause, the
            entity E may no longer be use-visible, resulting in errors. This
            should be rare and is easily fixed if it does occur.


                            Extensions to Ada 95

84.b/2      {8652/0059} {AI95-00131-01} Corrigendum: Convention C_Pass_By_Copy
            is new.


                         Wording Changes from Ada 95

84.c/2      {8652/0060} {AI95-00037-01} Corrigendum: Clarified the intent for
            Nul and Wide_Nul.

84.d/2      {AI95-00216-01} Specified that an unchecked union type (see
            B.3.3) is eligible for convention C_Pass_By_Copy.

84.e/2      {AI95-00258-01} Specified what happens if the To_C function tries
            to return a null string.

84.f/2      {AI95-00337-01} Clarified that the interface correspondences also
            apply to private types whose full types have the specified
            characteristics.

84.g/2      {AI95-00343-01} Clarified that a type must have convention
            C_Pass_By_Copy in order to be passed by copy (not just a type that
            could have that convention).

84.h/2      {AI95-00376-01} Added wording to make it clear that these
            facilities can also be used with C++.


                       Incompatibilities With Ada 2005

84.i/3      {AI05-0002-1} Correction: Added a definition of correspondences
            for function results. Also added wording to make it clear that we
            do not expect the implementation to conjure bounds for
            unconstrained arrays out of thin air. These changes allow (but
            don't require) compilers to reject unreasonable uses of array
            types. Such uses probably didn't work anyway (and probably were
            rejected, no matter what the language definition said), so little
            existing code should be impacted.


                           Extensions to Ada 2012

84.j/4      {AI12-0028-1} Corrigendum: The convention_identifiers
            C_Variadic_0, C_Variadic_1, and so on are new. These are
            classified as a correction as any implementation can add such
            identifiers and it is important that special conventions be
            available for variadic functions as typical x64 conventions are
            different for normal and variadic C functions.

84.k/4      {AI12-0135-1} Corrigendum: Defined the correspondence between an
            Ada enumeration type and a C enumeration type; implementations
            should support convention C for enumeration types.


B.3.1 The Package Interfaces.C.Strings


1/3 {AI05-0229-1} The package Interfaces.C.Strings declares types and
subprograms allowing an Ada program to allocate, reference, update, and free
C-style strings. In particular, the private type chars_ptr corresponds to a
common use of "char *" in C programs, and an object of this type can be passed
to a subprogram to which with Import => True, Convention => C has been
specified, and for which "char *" is the type of the argument of the C
function.


                              Static Semantics

2   The library package Interfaces.C.Strings has the following declaration:

3       package Interfaces.C.Strings is
           pragma Preelaborate(Strings);

4          type char_array_access is access all char_array;

5/2     {AI95-00161-01}    type chars_ptr is private;
           pragma Preelaborable_Initialization(chars_ptr);

6/2     {AI95-00276-01}    type chars_ptr_array
         is array (size_t range <>) of aliased chars_ptr;

7          Null_Ptr : constant chars_ptr;

8          function To_Chars_Ptr (Item      : in char_array_access;
                                  Nul_Check : in Boolean := False)
              return chars_ptr;

9          function New_Char_Array (Chars   : in char_array) return chars_ptr;

10         function New_String (Str : in String) return chars_ptr;

11         procedure Free (Item : in out chars_ptr);

12         Dereference_Error : exception;

13         function Value (Item : in chars_ptr) return char_array;

14         function Value (Item : in chars_ptr; Length : in size_t)
              return char_array;

15         function Value (Item : in chars_ptr) return String;

16         function Value (Item : in chars_ptr; Length : in size_t)
              return String;

17         function Strlen (Item : in chars_ptr) return size_t;

18         procedure Update (Item   : in chars_ptr;
                             Offset : in size_t;
                             Chars  : in char_array;
                             Check  : in Boolean := True);

19         procedure Update (Item   : in chars_ptr;
                             Offset : in size_t;
                             Str    : in String;
                             Check  : in Boolean := True);

20         Update_Error : exception;

21      private
           ... -- not specified by the language
        end Interfaces.C.Strings;

21.a        Discussion: The string manipulation types and subprograms appear
            in a child of Interfaces.C versus being there directly, since it
            is useful to have Interfaces.C specified as pragma Pure.

21.b        Differently named functions New_String and New_Char_Array are
            declared, since if there were a single overloaded function a call
            with a string literal as actual parameter would be ambiguous.

22  The type chars_ptr is C-compatible and corresponds to the use of C's "
char *" for a pointer to the first char in a char array terminated by nul.
When an object of type chars_ptr is declared, its value is by default set to
Null_Ptr, unless the object is imported (see B.1).

22.a        Discussion: The type char_array_access is not necessarily
            C-compatible, since an object of this type may carry "dope"
            information. The programmer should convert from char_array_access
            to chars_ptr for objects imported from, exported to, or passed to
            C.

23      function To_Chars_Ptr (Item      : in char_array_access;
                               Nul_Check : in Boolean := False)
           return chars_ptr;

24/3        {8652/0061} {AI95-00140-01} {AI05-0264-1} If Item is null, then
            To_Chars_Ptr returns Null_Ptr. If Item is not null, Nul_Check is
            True, and Item.all does not contain nul, then the function
            propagates Terminator_Error; otherwise, To_Chars_Ptr performs a
            pointer conversion with no allocation of memory.

25      function New_Char_Array (Chars   : in char_array) return chars_ptr;

26          This function returns a pointer to an allocated object initialized
            to Chars(Chars'First .. Index) & nul, where

27            * Index = Chars'Last if Chars does not contain nul, or

28            * Index is the smallest size_t value I such that Chars(I+1) =
                nul.

28.1        Storage_Error is propagated if the allocation fails.

29      function New_String (Str : in String) return chars_ptr;

30          This function is equivalent to New_Char_Array(To_C(Str)).

31      procedure Free (Item : in out chars_ptr);

32          If Item is Null_Ptr, then Free has no effect. Otherwise, Free
            releases the storage occupied by Value(Item), and resets Item to
            Null_Ptr.

33      function Value (Item : in chars_ptr) return char_array;

34/3        {AI05-0264-1} If Item = Null_Ptr, then Value propagates
            Dereference_Error. Otherwise, Value returns the prefix of the
            array of chars pointed to by Item, up to and including the first
            nul. The lower bound of the result is 0. If Item does not point to
            a nul-terminated string, then execution of Value is erroneous.

35      function Value (Item : in chars_ptr; Length : in size_t)
           return char_array;

36/3        {8652/0062} {AI95-00139-01} {AI05-0264-1} If Item = Null_Ptr, then
            Value propagates Dereference_Error. Otherwise, Value returns the
            shorter of two arrays, either the first Length chars pointed to by
            Item, or Value(Item). The lower bound of the result is 0. If
            Length is 0, then Value propagates Constraint_Error.

36.a        Ramification: Value(New_Char_Array(Chars)) = Chars if Chars does
            not contain nul; else Value(New_Char_Array( Chars)) is the prefix
            of Chars up to and including the first nul.

37      function Value (Item : in chars_ptr) return String;

38          Equivalent to To_Ada(Value(Item), Trim_Nul=>True).

39      function Value (Item : in chars_ptr; Length : in size_t)
           return String;

40/1        {8652/0063} {AI95-00177-01} Equivalent to To_Ada(Value(Item,
            Length) & nul, Trim_Nul=>True).

41      function Strlen (Item : in chars_ptr) return size_t;

42          Returns Val'Length-1 where Val = Value(Item); propagates
            Dereference_Error if Item = Null_Ptr.

42.a        Ramification: Strlen returns the number of chars in the array
            pointed to by Item, up to and including the char immediately
            before the first nul.

42.b        Strlen has the same possibility for erroneous execution as Value,
            in cases where the string has not been nul-terminated.

42.c        Strlen has the effect of C's strlen function.

43      procedure Update (Item   : in chars_ptr;
                          Offset : in size_t;
                          Chars  : in char_array;
                          Check  : Boolean := True);

44/1        {8652/0064} {AI95-00039-01} If Item = Null_Ptr, then Update
            propagates Dereference_Error. Otherwise, this procedure updates
            the value pointed to by Item, starting at position Offset, using
            Chars as the data to be copied into the array. Overwriting the nul
            terminator, and skipping with the Offset past the nul terminator,
            are both prevented if Check is True, as follows:

45            * Let N = Strlen(Item). If Check is True, then:

46                * If Offset+Chars'Length>N, propagate Update_Error.

47                * Otherwise, overwrite the data in the array pointed to by
                    Item, starting at the char at position Offset, with the
                    data in Chars.

48            * If Check is False, then processing is as above, but with no
                check that Offset+Chars'Length>N.

48.a        Ramification: If Chars contains nul, Update's effect may be to "
            shorten" the pointed-to char array.

49      procedure Update (Item   : in chars_ptr;
                          Offset : in size_t;
                          Str    : in String;
                          Check  : in Boolean := True);

50/2        {AI95-00242-01} Equivalent to Update(Item, Offset, To_C(Str,
            Append_Nul => False), Check).

50.a/2      Discussion: {AI95-00242-01} To truncate the Item to the length of
            Str, use Update(Item, Offset, To_C(Str), Check) instead of
            Update(Item, Offset, Str, Check). Note that when truncating Item,
            Item must be longer than Str.


                             Erroneous Execution

51  Execution of any of the following is erroneous if the Item parameter is
not null_ptr and Item does not point to a nul-terminated array of chars.

52    * a Value function not taking a Length parameter,

53    * the Free procedure,

54    * the Strlen function.

55  Execution of Free(X) is also erroneous if the chars_ptr X was not returned
by New_Char_Array or New_String.

56  Reading or updating a freed char_array is erroneous.

57  Execution of Update is erroneous if Check is False and a call with Check
equal to True would have propagated Update_Error.

        NOTES

58      9  New_Char_Array and New_String might be implemented either through
        the allocation function from the C environment ("malloc") or through
        Ada dynamic memory allocation ("new"). The key points are

59        * the returned value (a chars_ptr) is represented as a C "char *" so
            that it may be passed to C functions;

60        * the allocated object should be freed by the programmer via a call
            of Free, not by a called C function.


                         Inconsistencies With Ada 95

60.a/2      {AI95-00242-01} Amendment Correction: Update for a String
            parameter is now defined to not add a nul character. It did add a
            nul in Ada 95. This means that programs that used this behavior of
            Update to truncate a string will no longer work (the string will
            not be truncated). This change makes Update for a string
            consistent with Update for a char_array (no implicit nul is added
            to the end of a char_array).


                            Extensions to Ada 95

60.b/2      {AI95-00161-01} Amendment Correction: Added pragma
            Preelaborable_Initialization to type chars_ptr, so that it can be
            used in preelaborated units.

60.c/2      {AI95-00276-01} Amendment Correction: The components of
            chars_ptr_array are aliased so that it can be used to instantiate
            Interfaces.C.Pointers (that is its intended purpose, which is
            otherwise mysterious as it has no operations).


                         Wording Changes from Ada 95

60.d/2      {8652/0061} {AI95-00140-01} Corrigendum: Fixed the missing
            semantics of To_Char_Ptr when Nul_Check is False.

60.e/2      {8652/0062} {AI95-00139-01} Corrigendum: Fixed the missing
            semantics of Value when the Length is 0.

60.f/2      {8652/0063} {AI95-00177-01} Corrigendum: Corrected the definition
            of Value to avoid raising Terminator_Error.

60.g/2      {8652/0064} {AI95-00039-01} Corrigendum: Fixed the missing
            semantics of Update when Item is Null_Ptr.


B.3.2 The Generic Package Interfaces.C.Pointers


1   The generic package Interfaces.C.Pointers allows the Ada programmer to
perform C-style operations on pointers. It includes an access type Pointer,
Value functions that dereference a Pointer and deliver the designated array,
several pointer arithmetic operations, and "copy" procedures that copy the
contents of a source pointer into the array designated by a destination
pointer. As in C, it treats an object Ptr of type Pointer as a pointer to the
first element of an array, so that for example, adding 1 to Ptr yields a
pointer to the second element of the array.

2   The generic allows two styles of usage: one in which the array is
terminated by a special terminator element; and another in which the
programmer needs to keep track of the length.


                              Static Semantics

3   The generic library package Interfaces.C.Pointers has the following
declaration:

4       generic
           type Index is (<>);
           type Element is private;
           type Element_Array is array (Index range <>) of aliased Element;
           Default_Terminator : Element;
        package Interfaces.C.Pointers is
           pragma Preelaborate(Pointers);

5          type Pointer is access all Element;

6          function Value(Ref        : in Pointer;
                          Terminator : in Element := Default_Terminator)
              return Element_Array;

7          function Value(Ref    : in Pointer;
                          Length : in ptrdiff_t)
              return Element_Array;

8          Pointer_Error : exception;

9          -- C-style Pointer arithmetic

10/3    {AI05-0229-1}
           function "+" (Left : in Pointer;   Right : in ptrdiff_t) return Pointer
              with Convention => Intrinsic;
           function "+" (Left : in ptrdiff_t; Right : in Pointer)   return Pointer
              with Convention => Intrinsic;
           function "-" (Left : in Pointer;   Right : in ptrdiff_t) return Pointer
              with Convention => Intrinsic;
           function "-" (Left : in Pointer;   Right : in Pointer) return ptrdiff_t
              with Convention => Intrinsic;

11/3    {AI05-0229-1}    procedure Increment (Ref : in out Pointer)
              with Convention => Intrinsic;
           procedure Decrement (Ref : in out Pointer)
              with Convention => Intrinsic;

12/3    This paragraph was deleted.{AI05-0229-1}

13         function Virtual_Length (Ref        : in Pointer;
                                    Terminator : in Element := Default_Terminator)
              return ptrdiff_t;

14         procedure Copy_Terminated_Array
              (Source     : in Pointer;
               Target     : in Pointer;
               Limit      : in ptrdiff_t := ptrdiff_t'Last;
               Terminator : in Element :=  Default_Terminator);

15         procedure Copy_Array (Source  : in Pointer;
                                 Target  : in Pointer;
                                 Length  : in ptrdiff_t);

16      end Interfaces.C.Pointers;

17  The type Pointer is C-compatible and corresponds to one use of C's "
Element *". An object of type Pointer is interpreted as a pointer to the
initial Element in an Element_Array. Two styles are supported:

18    * Explicit termination of an array value with Default_Terminator (a
        special terminator value);

19    * Programmer-managed length, with Default_Terminator treated simply as a
        data element.

20      function Value(Ref        : in Pointer;
                       Terminator : in Element := Default_Terminator)
           return Element_Array;

21          This function returns an Element_Array whose value is the array
            pointed to by Ref, up to and including the first Terminator; the
            lower bound of the array is Index'First.
            Interfaces.C.Strings.Dereference_Error is propagated if Ref is
            null.

22      function Value(Ref    : in Pointer;
                       Length : in ptrdiff_t)
           return Element_Array;

23          This function returns an Element_Array comprising the first Length
            elements pointed to by Ref. The exception
            Interfaces.C.Strings.Dereference_Error is propagated if Ref is
            null.

24  The "+" and "-" functions perform arithmetic on Pointer values, based on
the Size of the array elements. In each of these functions, Pointer_Error is
propagated if a Pointer parameter is null.

25      procedure Increment (Ref : in out Pointer);

26          Equivalent to Ref := Ref+1.

27      procedure Decrement (Ref : in out Pointer);

28          Equivalent to Ref := Ref-1.

29      function Virtual_Length (Ref        : in Pointer;
                                 Terminator : in Element := Default_Terminator)
           return ptrdiff_t;

30          Returns the number of Elements, up to the one just before the
            first Terminator, in Value(Ref, Terminator).

31      procedure Copy_Terminated_Array
           (Source     : in Pointer;
            Target     : in Pointer;
            Limit      : in ptrdiff_t := ptrdiff_t'Last;
            Terminator : in Element := Default_Terminator);

32          This procedure copies Value(Source, Terminator) into the array
            pointed to by Target; it stops either after Terminator has been
            copied, or the number of elements copied is Limit, whichever
            occurs first. Dereference_Error is propagated if either Source or
            Target is null.

32.a        Ramification: It is the programmer's responsibility to ensure that
            elements are not copied beyond the logical length of the target
            array.

32.b        Implementation Note: The implementation has to take care to check
            the Limit first.

33      procedure Copy_Array (Source  : in Pointer;
                              Target  : in Pointer;
                              Length  : in ptrdiff_t);

34          This procedure copies the first Length elements from the array
            pointed to by Source, into the array pointed to by Target.
            Dereference_Error is propagated if either Source or Target is
            null.


                             Erroneous Execution

35  It is erroneous to dereference a Pointer that does not designate an
aliased Element.

35.a        Discussion: Such a Pointer could arise via "+", "-", Increment, or
            Decrement.

36  Execution of Value(Ref, Terminator) is erroneous if Ref does not designate
an aliased Element in an Element_Array terminated by Terminator.

37  Execution of Value(Ref, Length) is erroneous if Ref does not designate an
aliased Element in an Element_Array containing at least Length Elements
between the designated Element and the end of the array, inclusive.

38  Execution of Virtual_Length(Ref, Terminator) is erroneous if Ref does not
designate an aliased Element in an Element_Array terminated by Terminator.

39  Execution of Copy_Terminated_Array(Source, Target, Limit, Terminator) is
erroneous in either of the following situations:

40    * Execution of both Value(Source, Terminator) and Value(Source, Limit)
        are erroneous, or

41    * Copying writes past the end of the array containing the Element
        designated by Target.

42  Execution of Copy_Array(Source, Target, Length) is erroneous if either
Value(Source, Length) is erroneous, or copying writes past the end of the
array containing the Element designated by Target.

        NOTES

43      10  To compose a Pointer from an Element_Array, use 'Access on the
        first element. For example (assuming appropriate instantiations):

44          Some_Array   : Element_Array(0..5) ;
            Some_Pointer : Pointer := Some_Array(0)'Access;


                                  Examples

45  Example of Interfaces.C.Pointers:

46      with Interfaces.C.Pointers;
        with Interfaces.C.Strings;
        procedure Test_Pointers is
           package C renames Interfaces.C;
           package Char_Ptrs is
              new C.Pointers (Index              => C.size_t,
                              Element            => C.char,
                              Element_Array      => C.char_array,
                              Default_Terminator => C.nul);

47         use type Char_Ptrs.Pointer;
           subtype Char_Star is Char_Ptrs.Pointer;

48         procedure Strcpy (Target_Ptr, Source_Ptr : Char_Star) is
              Target_Temp_Ptr : Char_Star := Target_Ptr;
              Source_Temp_Ptr : Char_Star := Source_Ptr;
              Element : C.char;
           begin
              if Target_Temp_Ptr = null or Source_Temp_Ptr = null then
                 raise C.Strings.Dereference_Error;
              end if;

49/1    {8652/0065} {AI95-00142-01}       loop
                 Element             := Source_Temp_Ptr.all;
                 Target_Temp_Ptr.all := Element;
                 exit when C."="(Element, C.nul);
                 Char_Ptrs.Increment(Target_Temp_Ptr);
                 Char_Ptrs.Increment(Source_Temp_Ptr);
              end loop;
           end Strcpy;
        begin
           ...
        end Test_Pointers;


B.3.3 Unchecked Union Types


1/3 {AI95-00216-01} {AI05-0229-1} {AI05-0269-1} [Specifying aspect
Unchecked_Union to have the value True defines an interface correspondence
between a given discriminated type and some C union. The aspect requires that
the associated type shall be given a representation that allocates no space
for its discriminant(s).]

Paragraphs 2 through 3 were moved to Annex J, "Obsolescent Features".


                              Static Semantics

3.1/3 {AI05-0229-1} For a discriminated record type having a variant_part, the
following language-defined representation aspect may be specified:

3.2/3 Unchecked_Union
                The type of aspect Unchecked_Union is Boolean. If directly
                specified, the aspect_definition shall be a static expression.
                If not specified (including by inheritance), the aspect is
                False.

3.a/3       Aspect Description for Unchecked_Union: Type is used to interface
            to a C union type.


                               Legality Rules

Paragraphs 4 and 5 were deleted.

6/3 {AI95-00216-01} {AI05-0229-1} A type for which aspect Unchecked_Union is
True is called an unchecked union type. A subtype of an unchecked union type
is defined to be an unchecked union subtype. An object of an unchecked union
type is defined to be an unchecked union object.

7/2 {AI95-00216-01} All component subtypes of an unchecked union type shall be
C-compatible.

8/2 {AI95-00216-01} If a component subtype of an unchecked union type is
subject to a per-object constraint, then the component subtype shall be an
unchecked union subtype.

9/3 {AI95-00216-01} {AI05-0026-1} Any name that denotes a discriminant of an
object of an unchecked union type shall occur within the declarative region of
the type, and shall not occur within a record_representation_clause.

10/3 {AI95-00216-01} {AI05-0026-1} The type of a component declared in a
variant_part of an unchecked union type shall not need finalization. In
addition to the places where Legality Rules normally apply (see 12.3), this
rule also applies in the private part of an instance of a generic unit. For an
unchecked union type declared within the body of a generic unit, or within the
body of any of its descendant library units, no part of the type of a
component declared in a variant_part of the unchecked union type shall be of a
formal private type or formal private extension declared within the formal
part of the generic unit.

10.a/3      Reason: {AI05-0026-1} The last part is a classic assume-the-worst
            rule that avoids dependence on the actuals in a generic body. We
            did not include this in the definition of "needs finalization" as
            it has a bad interaction with the use of that term for the
            No_Nested_Finalization restriction.

11/2 {AI95-00216-01} The completion of an incomplete or private type
declaration having a known_discriminant_part shall not be an unchecked union
type.

12/2 {AI95-00216-01} An unchecked union subtype shall only be passed as a
generic actual parameter if the corresponding formal type has no known
discriminants or is an unchecked union type.

12.a/2      Ramification: This includes formal private types without a
            known_discriminant_part, formal derived types that do not inherit
            any discriminants (formal derived types do not have
            known_discriminant_parts), and formal derived types that are
            unchecked union types.


                              Static Semantics

13/2 {AI95-00216-01} An unchecked union type is eligible for convention C.

14/2 {AI95-00216-01} All objects of an unchecked union type have the same size.

15/2 {AI95-00216-01} Discriminants of objects of an unchecked union type are
of size zero.

16/2 {AI95-00216-01} Any check which would require reading a discriminant of
an unchecked union object is suppressed (see 11.5). These checks include:

17/2   * The check performed when addressing a variant component (i.e., a
        component that was declared in a variant part) of an unchecked union
        object that the object has this component (see 4.1.3).

18/2   * Any checks associated with a type or subtype conversion of a value of
        an unchecked union type (see 4.6). This includes, for example, the
        check associated with the implicit subtype conversion of an assignment
        statement.

19/2   * The subtype membership check associated with the evaluation of a
        qualified expression (see 4.7) or an uninitialized allocator (see
        4.8).

19.a/2      Discussion: If a suppressed check would have failed, execution is
            erroneous (see 11.5). An implementation is always allowed to make
            a suppressed check if it can somehow determine the discriminant
            value.


                              Dynamic Semantics

20/2 {AI95-00216-01} A view of an unchecked union object (including a type
conversion or function call) has inferable discriminants if it has a
constrained nominal subtype, unless the object is a component of an enclosing
unchecked union object that is subject to a per-object constraint and the
enclosing object lacks inferable discriminants.

21/2 {AI95-00216-01} An expression of an unchecked union type has inferable
discriminants if it is either a name of an object with inferable discriminants
or a qualified expression whose subtype_mark denotes a constrained subtype.

22/2 {AI95-00216-01} Program_Error is raised in the following cases:

23/2   * Evaluation of the predefined equality operator for an unchecked union
        type if either of the operands lacks inferable discriminants.

24/2   * Evaluation of the predefined equality operator for a type which has a
        subcomponent of an unchecked union type whose nominal subtype is
        unconstrained.

25/2   * Evaluation of a membership test if the subtype_mark denotes a
        constrained unchecked union subtype and the expression lacks inferable
        discriminants.

26/2   * Conversion from a derived unchecked union type to an unconstrained
        non-unchecked-union type if the operand of the conversion lacks
        inferable discriminants.

27/2   * Execution of the default implementation of the Write or Read
        attribute of an unchecked union type.

28/2   * Execution of the default implementation of the Output or Input
        attribute of an unchecked union type if the type lacks default
        discriminant values.

Paragraph 29 was deleted.

        NOTES

30/2    11  {AI95-00216-01} The use of an unchecked union to obtain the effect
        of an unchecked conversion results in erroneous execution (see 11.5).
        Execution of the following example is erroneous even if Float'Size =
        Integer'Size:

31/3        {AI05-0229-1} type T (Flag : Boolean := False) is
               record
                   case Flag is
                       when False =>
                           F1 : Float := 0.0;
                       when True =>
                           F2 : Integer := 0;
                   end case;
                end record
                with Unchecked_Union;

32/2        X : T;
            Y : Integer := X.F2; -- erroneous


                            Extensions to Ada 95

32.a/2      {AI95-00216-01} Pragma Unchecked_Union is new.


                       Incompatibilities With Ada 2005

32.b/3      {AI05-0026-1} Correction: The use of discriminants on
            Unchecked_Union types is now illegal in
            record_representation_clauses, as it makes no sense to specify a
            position for something that is not supposed to exist. It is very
            unlikely that this change will have any impact on existing code.


                           Extensions to Ada 2005

32.c/3      {AI05-0229-1} Aspect Unchecked_Union is new; pragma
            Unchecked_Union is now obsolescent.


                        Wording Changes from Ada 2005

32.d/3      {AI05-0026-1} Correction: Revised the rules to use the "needs
            finalization" definition, and eliminated generic contract issues.


B.4 Interfacing with COBOL


1/3 {AI05-0229-1} The facilities relevant to interfacing with the COBOL
language are the package Interfaces.COBOL and support for specifying the
Convention aspect with convention_identifier COBOL.

2   The COBOL interface package supplies several sets of facilities:

3     * A set of types corresponding to the native COBOL types of the
        supported COBOL implementation (so-called "internal COBOL
        representations"), allowing Ada data to be passed as parameters to
        COBOL programs

4     * A set of types and constants reflecting external data representations
        such as might be found in files or databases, allowing COBOL-generated
        data to be read by an Ada program, and Ada-generated data to be read
        by COBOL programs

5     * A generic package for converting between an Ada decimal type value and
        either an internal or external COBOL representation


                              Static Semantics

6   The library package Interfaces.COBOL has the following declaration:

7       package Interfaces.COBOL is
           pragma Preelaborate(COBOL);

8       -- Types and operations for internal data representations

9          type Floating      is digits implementation-defined;
           type Long_Floating is digits implementation-defined;

10         type Binary      is range implementation-defined;
           type Long_Binary is range implementation-defined;

11         Max_Digits_Binary      : constant := implementation-defined;
           Max_Digits_Long_Binary : constant := implementation-defined;

12/3    {AI05-0229-1}    type Decimal_Element  is mod implementation-defined;
           type Packed_Decimal is array (Positive range <>) of Decimal_Element
              with Pack;

13         type COBOL_Character is implementation-defined character type;

14         Ada_To_COBOL
         : array (Character) of COBOL_Character := implementation-defined;

15         COBOL_To_Ada
         : array (COBOL_Character) of Character := implementation-defined;

16/3    {AI05-0229-1}    type Alphanumeric
         is array (Positive range <>) of COBOL_Character
              with Pack;

17         function To_COBOL (Item : in String) return Alphanumeric;
           function To_Ada   (Item : in Alphanumeric) return String;

18         procedure To_COBOL (Item       : in String;
                               Target     : out Alphanumeric;
                               Last       : out Natural);

19         procedure To_Ada (Item     : in Alphanumeric;
                             Target   : out String;
                             Last     : out Natural);

20/3    {AI05-0229-1}    type Numeric
         is array (Positive range <>) of COBOL_Character
              with Pack;

21      -- Formats for COBOL data representations

22         type Display_Format is private;

23         Unsigned             : constant Display_Format;
           Leading_Separate     : constant Display_Format;
           Trailing_Separate    : constant Display_Format;
           Leading_Nonseparate  : constant Display_Format;
           Trailing_Nonseparate : constant Display_Format;

24         type Binary_Format is private;

25         High_Order_First  : constant Binary_Format;
           Low_Order_First   : constant Binary_Format;
           Native_Binary     : constant Binary_Format;

26         type Packed_Format is private;

27         Packed_Unsigned   : constant Packed_Format;
           Packed_Signed     : constant Packed_Format;

28      -- Types for external representation of COBOL binary data

29/3    {AI05-0229-1}    type Byte is mod 2**COBOL_Character'Size;
           type Byte_Array is array (Positive range <>) of Byte
              with Pack;

30         Conversion_Error : exception;

31         generic
              type Num is delta <> digits <>;
           package Decimal_Conversions is

32            -- Display Formats: data values are represented as Numeric

33            function Valid (Item   : in Numeric;
                              Format : in Display_Format) return Boolean;

34            function Length (Format : in Display_Format) return Natural;

35            function To_Decimal (Item   : in Numeric;
                                   Format : in Display_Format) return Num;

36            function To_Display (Item   : in Num;
                                   Format : in Display_Format) return Numeric;

37            -- Packed Formats: data values are represented as Packed_Decimal

38            function Valid (Item   : in Packed_Decimal;
                              Format : in Packed_Format) return Boolean;

39            function Length (Format : in Packed_Format) return Natural;

40            function To_Decimal (Item   : in Packed_Decimal;
                                   Format : in Packed_Format) return Num;

41            function To_Packed (Item   : in Num;
                                  Format : in Packed_Format) return Packed_Decimal;

42            -- Binary Formats: external data values are represented as Byte_Array

43            function Valid (Item   : in Byte_Array;
                              Format : in Binary_Format) return Boolean;

44            function Length (Format : in Binary_Format) return Natural;
              function To_Decimal (Item   : in Byte_Array;
                                   Format : in Binary_Format) return Num;

45            function To_Binary (Item   : in Num;
                                Format : in Binary_Format) return Byte_Array;

46            -- Internal Binary formats: data values are of type Binary or Long_Binary

47            function To_Decimal (Item : in Binary)      return Num;
              function To_Decimal (Item : in Long_Binary) return Num;

48            function To_Binary      (Item : in Num)  return Binary;
              function To_Long_Binary (Item : in Num)  return Long_Binary;

49         end Decimal_Conversions;

50      private
           ... -- not specified by the language
        end Interfaces.COBOL;

50.a/1      Implementation defined: The types Floating, Long_Floating, Binary,
            Long_Binary, Decimal_Element, and COBOL_Character; and the
            initializations of the variables Ada_To_COBOL and COBOL_To_Ada, in
            Interfaces.COBOL.

51  Each of the types in Interfaces.COBOL is COBOL-compatible.

52  The types Floating and Long_Floating correspond to the native types in
COBOL for data items with computational usage implemented by floating point.
The types Binary and Long_Binary correspond to the native types in COBOL for
data items with binary usage, or with computational usage implemented by
binary.

53  Max_Digits_Binary is the largest number of decimal digits in a numeric
value that is represented as Binary. Max_Digits_Long_Binary is the largest
number of decimal digits in a numeric value that is represented as Long_Binary.

54  The type Packed_Decimal corresponds to COBOL's packed-decimal usage.

55  The type COBOL_Character defines the run-time character set used in the
COBOL implementation. Ada_To_COBOL and COBOL_To_Ada are the mappings between
the Ada and COBOL run-time character sets.

55.a        Reason: The character mappings are visible variables, since the
            user needs the ability to modify them at run time.

56  Type Alphanumeric corresponds to COBOL's alphanumeric data category.

57  Each of the functions To_COBOL and To_Ada converts its parameter based on
the mappings Ada_To_COBOL and COBOL_To_Ada, respectively. The length of the
result for each is the length of the parameter, and the lower bound of the
result is 1. Each component of the result is obtained by applying the relevant
mapping to the corresponding component of the parameter.

58  Each of the procedures To_COBOL and To_Ada copies converted elements from
Item to Target, using the appropriate mapping (Ada_To_COBOL or COBOL_To_Ada,
respectively). The index in Target of the last element assigned is returned in
Last (0 if Item is a null array). If Item'Length exceeds Target'Length,
Constraint_Error is propagated.

59  Type Numeric corresponds to COBOL's numeric data category with display
usage.

60  The types Display_Format, Binary_Format, and Packed_Format are used in
conversions between Ada decimal type values and COBOL internal or external
data representations. The value of the constant Native_Binary is either
High_Order_First or Low_Order_First, depending on the implementation.

61      function Valid (Item   : in Numeric;
                        Format : in Display_Format) return Boolean;

62          The function Valid checks that the Item parameter has a value
            consistent with the value of Format. If the value of Format is
            other than Unsigned, Leading_Separate, and Trailing_Separate, the
            effect is implementation defined. If Format does have one of these
            values, the following rules apply:

63/3          * {8652/0066} {AI95-00071-01} {AI05-0264-1} Format=Unsigned: if
                Item comprises one or more decimal digit characters, then
                Valid returns True, else it returns False.

64/1          * {8652/0066} {AI95-00071-01} Format=Leading_Separate: if Item
                comprises a single occurrence of the plus or minus sign
                character, and then one or more decimal digit characters, then
                Valid returns True, else it returns False.

65/1          * {8652/0066} {AI95-00071-01} Format=Trailing_Separate: if Item
                comprises one or more decimal digit characters and finally a
                plus or minus sign character, then Valid returns True, else it
                returns False.

66      function Length (Format : in Display_Format) return Natural;

67          The Length function returns the minimal length of a Numeric value
            sufficient to hold any value of type Num when represented as
            Format.

68      function To_Decimal (Item   : in Numeric;
                             Format : in Display_Format) return Num;

69          Produces a value of type Num corresponding to Item as represented
            by Format. The number of digits after the assumed radix point in
            Item is Num'Scale. Conversion_Error is propagated if the value
            represented by Item is outside the range of Num.

69.a        Discussion: There is no issue of truncation versus rounding, since
            the number of decimal places is established by Num'Scale.

70      function To_Display (Item   : in Num;
                             Format : in Display_Format) return Numeric;

71/1        {8652/0067} {AI95-00072-01} This function returns the Numeric
            value for Item, represented in accordance with Format. The length
            of the returned value is Length(Format), and the lower bound is 1.
            Conversion_Error is propagated if Num is negative and Format is
            Unsigned.

72      function Valid (Item   : in Packed_Decimal;
                        Format : in Packed_Format) return Boolean;

73          This function returns True if Item has a value consistent with
            Format, and False otherwise. The rules for the formation of
            Packed_Decimal values are implementation defined.

74      function Length (Format : in Packed_Format) return Natural;

75          This function returns the minimal length of a Packed_Decimal value
            sufficient to hold any value of type Num when represented as
            Format.

76      function To_Decimal (Item   : in Packed_Decimal;
                             Format : in Packed_Format) return Num;

77          Produces a value of type Num corresponding to Item as represented
            by Format. Num'Scale is the number of digits after the assumed
            radix point in Item. Conversion_Error is propagated if the value
            represented by Item is outside the range of Num.

78      function To_Packed (Item   : in Num;
                            Format : in Packed_Format) return Packed_Decimal;

79/1        {8652/0067} {AI95-00072-01} This function returns the
            Packed_Decimal value for Item, represented in accordance with
            Format. The length of the returned value is Length(Format), and
            the lower bound is 1. Conversion_Error is propagated if Num is
            negative and Format is Packed_Unsigned.

80      function Valid (Item   : in Byte_Array;
                        Format : in Binary_Format) return Boolean;

81          This function returns True if Item has a value consistent with
            Format, and False otherwise.

81.a        Ramification: This function returns False only when the
            represented value is outside the range of Num.

82      function Length (Format : in Binary_Format) return Natural;

83          This function returns the minimal length of a Byte_Array value
            sufficient to hold any value of type Num when represented as
            Format.

84      function To_Decimal (Item   : in Byte_Array;
                             Format : in Binary_Format) return Num;

85          Produces a value of type Num corresponding to Item as represented
            by Format. Num'Scale is the number of digits after the assumed
            radix point in Item. Conversion_Error is propagated if the value
            represented by Item is outside the range of Num.

86      function To_Binary (Item   : in Num;
                            Format : in Binary_Format) return Byte_Array;

87/1        {8652/0067} {AI95-00072-01} This function returns the Byte_Array
            value for Item, represented in accordance with Format. The length
            of the returned value is Length(Format), and the lower bound is 1.

88      function To_Decimal (Item : in Binary)      return Num;
        
        function To_Decimal (Item : in Long_Binary) return Num;

89          These functions convert from COBOL binary format to a
            corresponding value of the decimal type Num. Conversion_Error is
            propagated if Item is too large for Num.

89.a        Ramification: There is no rescaling performed on the conversion.
            That is, the returned value in each case is a "bit copy" if Num
            has a binary radix. The programmer is responsible for maintaining
            the correct scale.

90      function To_Binary      (Item : in Num)  return Binary;
        
        function To_Long_Binary (Item : in Num)  return Long_Binary;

91          These functions convert from Ada decimal to COBOL binary format.
            Conversion_Error is propagated if the value of Item is too large
            to be represented in the result type.

91.a        Discussion: One style of interface supported for COBOL, similar to
            what is provided for C, is the ability to call and pass parameters
            to an existing COBOL program. Thus the interface package supplies
            types that can be used in an Ada program as parameters to
            subprograms whose bodies will be in COBOL. These types map to
            COBOL's alphanumeric and numeric data categories.

91.b        Several types are provided for support of alphanumeric data. Since
            COBOL's run-time character set is not necessarily the same as
            Ada's, Interfaces.COBOL declares an implementation-defined
            character type COBOL_Character, and mappings between Character and
            COBOL_Character. These mappings are visible variables (rather
            than, say, functions or constant arrays), since in the situation
            where COBOL_Character is EBCDIC, the flexibility of dynamically
            modifying the mappings is needed. Corresponding to COBOL's
            alphanumeric data is the string type Alphanumeric.

91.c        Numeric data may have either a "display" or "computational"
            representation in COBOL. On the Ada side, the data is of a decimal
            fixed point type. Passing an Ada decimal data item to a COBOL
            program requires conversion from the Ada decimal type to some type
            that reflects the representation expected on the COBOL side.

91.d          * Computational Representation

91.e            Floating point representation is modeled by Ada floating point
                types, Floating and Long_Floating. Conversion between these
                types and Ada decimal types is obtained directly, since the
                type name serves as a conversion function.

91.f            Binary representation is modeled by an Ada integer type,
                Binary, and possibly other types such as Long_Binary.
                Conversion between, say, Binary and a decimal type is through
                functions from an instantiation of the generic package
                Decimal_Conversions.

91.g            Packed decimal representation is modeled by the Ada array type
                Packed_Decimal. Conversion between packed decimal and a
                decimal type is through functions from an instantiation of the
                generic package Decimal_Conversions.

91.h          * Display Representation

91.i            Display representation for numeric data is modeled by the
                array type Numeric. Conversion between display representation
                and a decimal type is through functions from an instantiation
                of the generic package Decimal_Conversions. A parameter to the
                conversion function indicates the desired interpretation of
                the data (e.g., signed leading separate, etc.)

91.j/3      {AI05-0229-1} The Convention of a record type may be specified as
            COBOL to direct the compiler to choose a COBOL-compatible
            representation for objects of the type.

91.k        The package Interfaces.COBOL allows the Ada programmer to deal
            with data from files (or databases) created by a COBOL program.
            For data that is alphanumeric, or in display or packed decimal
            format, the approach is the same as for passing parameters
            (instantiate Decimal_Conversions to obtain the needed conversion
            functions). For binary data, the external representation is
            treated as a Byte array, and an instantiation of Decimal_IO
            produces a package that declares the needed conversion functions.
            A parameter to the conversion function indicates the desired
            interpretation of the data (e.g., high- versus low-order byte
            first).


                         Implementation Requirements

92/3 {AI05-0229-1} An implementation shall support specifying aspect
Convention with a COBOL convention_identifier for a COBOL-eligible type (see
B.1).

92.a        Ramification: An implementation supporting this package shall
            ensure that if the bounds of a Packed_Decimal, Alphanumeric, or
            Numeric variable are static, then the representation of the object
            comprises solely the array components (that is, there is no
            implicit run-time "descriptor" that is part of the object).


                         Implementation Permissions

93  An implementation may provide additional constants of the private types
Display_Format, Binary_Format, or Packed_Format.

93.a        Reason: This is to allow exploitation of other external formats
            that may be available in the COBOL implementation.

94  An implementation may provide further floating point and integer types in
Interfaces.COBOL to match additional native COBOL types, and may also supply
corresponding conversion functions in the generic package Decimal_Conversions.


                            Implementation Advice

95  An Ada implementation should support the following interface
correspondences between Ada and COBOL.

96    * An Ada access T parameter is passed as a "BY REFERENCE" data item of
        the COBOL type corresponding to T.

97    * An Ada in scalar parameter is passed as a "BY CONTENT" data item of
        the corresponding COBOL type.

98    * Any other Ada parameter is passed as a "BY REFERENCE" data item of the
        COBOL type corresponding to the Ada parameter type; for scalars, a
        local copy is used if necessary to ensure by-copy semantics.

98.a/2      Implementation Advice: If COBOL interfacing is supported, the
            interface correspondences between Ada and COBOL should be
            supported.

        NOTES

99/3    12  {AI05-0229-1} An implementation is not required to support
        specifying aspect Convention for access types, nor is it required to
        support specifying aspects Import, Export, or Convention for
        functions.

99.a        Reason: COBOL does not have a pointer facility, and a COBOL
            program does not return a value.

100     13  If an Ada subprogram is exported to COBOL, then a call from COBOL
        call may specify either "BY CONTENT" or "BY REFERENCE".


                                  Examples

101 Examples of Interfaces.COBOL:

102     with Interfaces.COBOL;
        procedure Test_Call is

103        -- Calling a foreign COBOL program
           -- Assume that a COBOL program PROG has the following declaration
           --  in its LINKAGE section:
           --  01 Parameter-Area
           --     05 NAME   PIC X(20).
           --     05 SSN    PIC X(9).
           --     05 SALARY PIC 99999V99 USAGE COMP.
           -- The effect of PROG is to update SALARY based on some algorithm

104        package COBOL renames Interfaces.COBOL;

105        type Salary_Type is delta 0.01 digits 7;

106/3   {AI05-0229-1}    type COBOL_Record is
              record
                 Name   : COBOL.Numeric(1..20);
                 SSN    : COBOL.Numeric(1..9);
                 Salary : COBOL.Binary;  -- Assume Binary = 32 bits
              end record
              with Convention => COBOL;

107/3   {AI05-0229-1}    procedure Prog (Item : in out COBOL_Record)
              with Import => True, Convention => COBOL;

108        package Salary_Conversions is
              new COBOL.Decimal_Conversions(Salary_Type);

109        Some_Salary : Salary_Type := 12_345.67;
           Some_Record : COBOL_Record :=
              (Name   => "Johnson, John       ",
               SSN    => "111223333",
               Salary => Salary_Conversions.To_Binary(Some_Salary));

110     begin
           Prog (Some_Record);
           ...
        end Test_Call;

111     with Interfaces.COBOL;
        with COBOL_Sequential_IO; -- Assumed to be supplied by implementation
        procedure Test_External_Formats is

112        -- Using data created by a COBOL program
           -- Assume that a COBOL program has created a sequential file with
           --  the following record structure, and that we need to
           --  process the records in an Ada program
           --  01 EMPLOYEE-RECORD
           --     05 NAME    PIC X(20).
           --     05 SSN     PIC X(9).
           --     05 SALARY  PIC 99999V99 USAGE COMP.
           --     05 ADJUST  PIC S999V999 SIGN LEADING SEPARATE.
           -- The COMP data is binary (32 bits), high-order byte first

113        package COBOL renames Interfaces.COBOL;

114        type Salary_Type      is delta 0.01  digits 7;
           type Adjustments_Type is delta 0.001 digits 6;

115/3   {AI05-0229-1}
           type COBOL_Employee_Record_Type is  -- External representation
              record
                 Name    : COBOL.Alphanumeric(1..20);
                 SSN     : COBOL.Alphanumeric(1..9);
                 Salary  : COBOL.Byte_Array(1..4);
                 Adjust  : COBOL.Numeric(1..7);  -- Sign and 6 digits
              end record
              with Convention => COBOL;

116        package COBOL_Employee_IO is
              new COBOL_Sequential_IO(COBOL_Employee_Record_Type);
           use COBOL_Employee_IO;

117        COBOL_File : File_Type;

118        type Ada_Employee_Record_Type is  -- Internal representation
              record
                 Name    : String(1..20);
                 SSN     : String(1..9);
                 Salary  : Salary_Type;
                 Adjust  : Adjustments_Type;
              end record;

119        COBOL_Record : COBOL_Employee_Record_Type;
           Ada_Record   : Ada_Employee_Record_Type;

120        package Salary_Conversions is
              new COBOL.Decimal_Conversions(Salary_Type);
           use Salary_Conversions;

121        package Adjustments_Conversions is
              new COBOL.Decimal_Conversions(Adjustments_Type);
           use Adjustments_Conversions;

122     begin
           Open (COBOL_File, Name => "Some_File");

123        loop
             Read (COBOL_File, COBOL_Record);

124          Ada_Record.Name := To_Ada(COBOL_Record.Name);
             Ada_Record.SSN  := To_Ada(COBOL_Record.SSN);
             Ada_Record.Salary :=
                To_Decimal(COBOL_Record.Salary, COBOL.High_Order_First);
             Ada_Record.Adjust :=
                To_Decimal(COBOL_Record.Adjust, COBOL.Leading_Separate);
             ... -- Process Ada_Record
           end loop;
        exception
           when End_Error => ...
        end Test_External_Formats;


                         Wording Changes from Ada 95

124.a/2     {8652/0066} {AI95-00071-01} Corrigendum: Corrected the definition
            of Valid to match COBOL.

124.b/2     {8652/0067} {AI95-00072-01} Corrigendum: Specified the bounds of
            the results of To_Display, To_Packed, and To_Binary.


B.5 Interfacing with Fortran


1/3 {AI05-0229-1} The facilities relevant to interfacing with the Fortran
language are the package Interfaces.Fortran and support for specifying the
Convention aspect with convention_identifier Fortran.

2   The package Interfaces.Fortran defines Ada types whose representations are
identical to the default representations of the Fortran intrinsic types
Integer, Real, Double Precision, Complex, Logical, and Character in a
supported Fortran implementation. These Ada types can therefore be used to
pass objects between Ada and Fortran programs.


                              Static Semantics

3   The library package Interfaces.Fortran has the following declaration:

4       with Ada.Numerics.Generic_Complex_Types;  -- see G.1.1
        pragma Elaborate_All(Ada.Numerics.Generic_Complex_Types);
        package Interfaces.Fortran is
           pragma Pure(Fortran);

5          type Fortran_Integer is range implementation-defined;

6          type Real             is digits implementation-defined;
           type Double_Precision is digits implementation-defined;

7          type Logical is new Boolean;

8          package Single_Precision_Complex_Types is
              new Ada.Numerics.Generic_Complex_Types (Real);

9          type Complex is new Single_Precision_Complex_Types.Complex;

10         subtype Imaginary is Single_Precision_Complex_Types.Imaginary;
           i : Imaginary renames Single_Precision_Complex_Types.i;
           j : Imaginary renames Single_Precision_Complex_Types.j;

11         type Character_Set is implementation-defined character type;

12/3    {AI05-0229-1}    type Fortran_Character
         is array (Positive range <>) of Character_Set
              with Pack;

13         function To_Fortran (Item : in Character) return Character_Set;
           function To_Ada (Item : in Character_Set) return Character;

14         function To_Fortran (Item : in String) return Fortran_Character;
           function To_Ada     (Item : in Fortran_Character) return String;

15         procedure To_Fortran (Item       : in String;
                                 Target     : out Fortran_Character;
                                 Last       : out Natural);

16         procedure To_Ada (Item     : in Fortran_Character;
                             Target   : out String;
                             Last     : out Natural);

17      end Interfaces.Fortran;

17.a.1/1    Implementation defined: The types Fortran_Integer, Real,
            Double_Precision, and Character_Set in Interfaces.Fortran.

17.a        Ramification: The means by which the Complex type is provided in
            Interfaces.Fortran creates a dependence of Interfaces.Fortran on
            Numerics.Generic_Complex_Types (see G.1.1). This dependence is
            intentional and unavoidable, if the Fortran-compatible Complex
            type is to be useful in Ada code without duplicating facilities
            defined elsewhere.

18  The types Fortran_Integer, Real, Double_Precision, Logical, Complex, and
Fortran_Character are Fortran-compatible.

19  The To_Fortran and To_Ada functions map between the Ada type Character and
the Fortran type Character_Set, and also between the Ada type String and the
Fortran type Fortran_Character. The To_Fortran and To_Ada procedures have
analogous effects to the string conversion subprograms found in
Interfaces.COBOL.


                         Implementation Requirements

20/3 {AI05-0229-1} An implementation shall support specifying aspect
Convention with a Fortran convention_identifier for a Fortran-eligible type
(see B.1).


                         Implementation Permissions

21  An implementation may add additional declarations to the Fortran interface
packages. For example, the Fortran interface package for an implementation of
Fortran 77 (ANSI X3.9-1978) that defines types like Integer*n, Real*n,
Logical*n, and Complex*n may contain the declarations of types named Integer_-
Star_n, Real_Star_n, Logical_Star_n, and Complex_Star_n. (This convention
should not apply to Character*n, for which the Ada analog is the constrained
array subtype Fortran_Character (1..n).) Similarly, the Fortran interface
package for an implementation of Fortran 90 that provides multiple kinds of
intrinsic types, e.g. Integer (Kind=n), Real (Kind=n), Logical (Kind=n),
Complex (Kind=n), and Character (Kind=n), may contain the declarations of
types with the recommended names Integer_Kind_n, Real_Kind_n, Logical_Kind_n,
Complex_Kind_n, and Character_Kind_n.

21.a        Discussion: Implementations may add auxiliary declarations as
            needed to assist in the declarations of additional
            Fortran-compatible types. For example, if a double precision
            complex type is defined, then Numerics.Generic_Complex_Types may
            be instantiated for the double precision type. Similarly, if a
            wide character type is defined to match a Fortran 90 wide
            character type (accessible in Fortran 90 with the Kind modifier),
            then an auxiliary character set may be declared to serve as its
            component type.


                            Implementation Advice

22  An Ada implementation should support the following interface
correspondences between Ada and Fortran:

23    * An Ada procedure corresponds to a Fortran subroutine.

24    * An Ada function corresponds to a Fortran function.

25    * An Ada parameter of an elementary, array, or record type T is passed
        as a T(F) argument to a Fortran procedure, where T(F) is the Fortran
        type corresponding to the Ada type T, and where the INTENT attribute
        of the corresponding dummy argument matches the Ada formal parameter
        mode; the Fortran implementation's parameter passing conventions are
        used. For elementary types, a local copy is used if necessary to
        ensure by-copy semantics.

26    * An Ada parameter of an access-to-subprogram type is passed as a
        reference to a Fortran procedure whose interface corresponds to the
        designated subprogram's specification.

26.a/2      Implementation Advice: If Fortran interfacing is supported, the
            interface correspondences between Ada and Fortran should be
            supported.

        NOTES

27      14  An object of a Fortran-compatible record type, declared in a
        library package or subprogram, can correspond to a Fortran common
        block; the type also corresponds to a Fortran "derived type".


                                  Examples

28  Example of Interfaces.Fortran:

29      with Interfaces.Fortran;
        use Interfaces.Fortran;
        procedure Ada_Application is

30/3    {AI05-0229-1}    type Fortran_Matrix is array (Integer range <>,
                                         Integer range <>) of Double_Precision
              with Convention => Fortran;                  -- stored in Fortran's
                                                           -- column-major order
           procedure Invert (Rank : in Fortran_Integer; X : in out Fortran_Matrix)
              with Import => True, Convention => Fortran; -- a Fortran subroutine

31         Rank      : constant Fortran_Integer := 100;
           My_Matrix : Fortran_Matrix (1 .. Rank, 1 .. Rank);

32      begin

33         ...
           My_Matrix := ...;
           ...
           Invert (Rank, My_Matrix);
           ...

34      end Ada_Application;

Generated by dwww version 1.15 on Sat Jun 15 14:49:16 CEST 2024.