B.3 Interfacing with C

From OC Systems Wiki!
Jump to: navigation, search

The facilities relevant to interfacing with the C language are the package Interfaces.C and its children; support for the Import, Export, and Convention pragmas with convention_identifier C; and support for the Convention pragma with convention_identifier C_Pass_By_Copy.

The package Interfaces.C contains the basic types, constants and subprograms that allow an Ada program to pass scalars and strings to C functions.

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>;

 
    nul : constant char := implementation-defined;

    function To_C   (Item in Character) return char;

    function To_Ada (Item in char) return Character;

    type char_array is array (size_t range <>) of aliased char;
    pragma Pack(char_array);
    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

    type wchar_t is <implementation-defined character type>;

    wide_nul : constant wchar_t := implementation-defined;

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

    type wchar_array is array (size_t range <>) of aliased wchar_t;

    pragma Pack(wchar_array);

    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);

    Terminator_Error : exception;

end Interfaces.C;

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

The types int, short, long, unsigned, ptrdiff_t, size_t, double, char, and wchar_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.

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.

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;

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.

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.

A Convention pragma with convention_identifier C_Pass_By_Copy shall only be applied to a type.

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 a record type that has no discriminants and that only has components with statically constrained subtypes, and each component is C-compatible.

If a type is C_Pass_By_Copy-compatible then it is also C-compatible.

Implementation Requirements

An implementation shall support pragma Convention with a C convention_identifier for a C-eligible type (see B.1). An implementation shall support pragma 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.

Implementation Advice

The constants nul and wide_nul 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.
  • An Ada function corresponds to a non-void C function.
  • 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.
  • An Ada parameter of a C_Pass_By_Copy-compatible (record) type T, 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.
  • An Ada parameter of a record type T, of any mode, other than an in parameter of a C_Pass_By_Copy-compatible type, 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.

Notes

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

10  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).

11  There is no explicit support for C's union types. Unchecked conversions can be used to obtain the effect of C unions.

12  A C function that takes a variable number of arguments 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.

    -- 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);

    pragma Import(C, Strcpy, "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;

Copyright © 1992,1993,1994,1995 Intermetrics, Inc.
Copyright © 2000 The MITRE Corporation, Inc. Ada Reference Manual