B.3 Interfacing with C and C++
{
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.
{
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
The library package
Interfaces.C has the following declaration:
package Interfaces.C
is
pragma Pure(C);
-- Declarations based on C's <limits.h>
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
-- Signed and Unsigned Integers
type int
is range implementation-defined;
type short
is range implementation-defined;
type long
is range implementation-defined;
type signed_char
is range SCHAR_MIN .. SCHAR_MAX;
for signed_char'Size
use CHAR_BIT;
type unsigned
is mod implementation-defined;
type unsigned_short
is mod implementation-defined;
type unsigned_long
is mod implementation-defined;
type unsigned_char
is mod (UCHAR_MAX+1);
for unsigned_char'Size
use CHAR_BIT;
subtype plain_char
is implementation-defined;
type ptrdiff_t
is range implementation-defined;
type size_t
is mod implementation-defined;
-- Floating Point
type C_float
is digits implementation-defined;
type double
is digits implementation-defined;
type long_double
is digits implementation-defined;
-- Characters and Strings
type char
is <implementation-defined character type>;
function To_C (Item :
in Character)
return char;
function To_Ada (Item :
in char)
return Character;
{
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;
function Is_Nul_Terminated (Item :
in char_array)
return Boolean;
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;
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);
-- Wide Character and Wide String
function To_C (Item :
in Wide_Character)
return wchar_t;
function To_Ada (Item :
in wchar_t )
return Wide_Character;
{
AI05-0229-1}
type wchar_array
is array (size_t
range <>)
of aliased wchar_t
with Pack;
function Is_Nul_Terminated (Item :
in wchar_array)
return Boolean;
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);
{
AI95-00285-01}
--
ISO/IEC 10646:2003 compatible types defined by ISO/IEC TR 19769:2004.{
AI95-00285-01}
type char16_t
is <implementation-defined character type>;
char16_nul :
constant char16_t :=
implementation-defined;
function To_C (Item :
in Wide_Character)
return char16_t;
function To_Ada (Item :
in char16_t)
return Wide_Character;
{
AI05-0229-1}
type char16_array
is array (size_t
range <>)
of aliased char16_t
with Pack;
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;
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);
{
AI95-00285-01}
type char32_t
is <implementation-defined character type>;
char32_nul :
constant char32_t :=
implementation-defined;
function To_C (Item :
in Wide_Wide_Character)
return char32_t;
function To_Ada (Item :
in char32_t)
return Wide_Wide_Character;
{
AI05-0229-1}
type char32_array
is array (size_t
range <>)
of aliased char32_t
with Pack;
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;
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);
Terminator_Error :
exception;
end Interfaces.C;
Implementation defined: The definitions
of certain types and constants in Interfaces.C.
Each of the types declared in Interfaces.C is C-compatible.
{
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.
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.
The type of the subtype
plain_char is either signed_char or unsigned_char, depending on the C
implementation.
function To_C (Item : in Character) return char;
function To_Ada (Item : in char ) return Character;
The functions To_C
and To_Ada map between the Ada type Character and the C type char.
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.
The following
definition is equivalent to the above summary:
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.
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.
function Is_Nul_Terminated (Item : in char_array) return Boolean;
The result of Is_Nul_Terminated
is True if Item contains nul, and is False otherwise.
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;
{
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.
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.
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);
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.
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.
function Is_Nul_Terminated (Item : in wchar_array) return Boolean;
The result of Is_Nul_Terminated
is True if Item contains wide_nul, and is False otherwise.
function To_C (Item : in Wide_Character) return wchar_t;
function To_Ada (Item : in wchar_t ) return Wide_Character;
To_C and To_Ada
provide the mappings between the Ada and C wide character types.
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);
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.
function Is_Nul_Terminated (Item : in char16_array) return Boolean;
{
AI95-00285-01}
The result of Is_Nul_Terminated is True if Item contains char16_nul,
and is False otherwise.
function To_C (Item : in Wide_Character) return char16_t;
function To_Ada (Item : in char16_t ) return Wide_Character;
{
AI95-00285-01}
To_C and To_Ada provide mappings between the Ada and C 16-bit character
types.
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);
{
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.
function Is_Nul_Terminated (Item : in char32_array) return Boolean;
{
AI95-00285-01}
The result of Is_Nul_Terminated is True if Item contains char16_nul,
and is False otherwise.
function To_C (Item : in Wide_Wide_Character) return char32_t;
function To_Ada (Item : in char32_t ) return Wide_Wide_Character;
{
AI95-00285-01}
To_C and To_Ada provide mappings between the Ada and C 32-bit character
types.
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);
{
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.
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.
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:
type char_array is array (size_t range <>) of Char;
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 *.
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.
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.
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.
{
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.
{
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.
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
{
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
An implementation may provide additional declarations
in the C interface packages.
{
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;
for a function with an unconstrained array result
subtype;
for an object whose nominal subtype is an unconstrained
array subtype.
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
Implementation Advice: The constants
nul, wide_nul, char16_nul, and char32_nul in package Interfaces.C should
have a representation of zero.
An implementation should support the following interface
correspondences between Ada and C.
An Ada procedure corresponds to a void-returning
C function.
Discussion: The programmer can also choose
an Ada procedure when the C function returns an int that is to be discarded.
An Ada function corresponds to a non-void C function.
{
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.
An Ada in scalar parameter is passed as
a scalar argument to a C function.
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.
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.
{
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.
{
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.
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.
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.
{
AI05-0002-1}
An Ada parameter of a private type is passed as specified for the full
view of the type.
{
AI05-0002-1}
The rules of correspondence given above for parameters of mode
in
also apply to the return object of a function.
Implementation Advice: If C interfacing
is supported, the interface correspondences between Ada and C should
be supported.
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.
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).
8 {
AI12-0028-1}
A variadic C function can correspond to several Ada subprograms, taking
various specific numbers and types of parameters.
Examples
Example of using
the Interfaces.C package:
--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.
{
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";
Chars1 : C.char_array(1..20);
Chars2 : C.char_array(1..20);
begin
Chars2(1..6) := "qwert" & C.nul;
Strcpy(Chars1, Chars2);
-- Now Chars1(1..6) = "qwert" & C.Nul
end Test;
Incompatibilities With Ada 95
{
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
Wording Changes from Ada 95
{
AI95-00216-01}
Specified that an unchecked union type (see
B.3.3)
is eligible for convention C_Pass_By_Copy.
{
AI95-00258-01}
Specified what happens if the To_C function tries to return a null string.
{
AI95-00337-01}
Clarified that the interface correspondences also apply to private types
whose full types have the specified characteristics.
{
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).
{
AI95-00376-01}
Added wording to make it clear that these facilities can also be used
with C++.
Incompatibilities With Ada 2005
{
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
{
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.
{
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.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe
