B.3 Interfacing with C and C++
This Reference Manual output has not been verified, and may contain omissions or errors. Report any problems on the tracking issue
{8652/0059} 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.
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
3The library package Interfaces.C has the following declaration:
package Interfaces.C
with Pure is
5-- Declarations based on C's <limits.h>
6CHAR_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;
8type signed_char is range SCHAR_MIN .. SCHAR_MAX;
for signed_char'Size use CHAR_BIT;
9type unsigned is mod implementation-defined;
type unsigned_short is mod implementation-defined;
type unsigned_long is mod implementation-defined;
10type unsigned_char is mod (UCHAR_MAX+1);
for unsigned_char'Size use CHAR_BIT;
11subtype plain_char is implementation-defined;
12type ptrdiff_t is range implementation-defined;
13type size_t is mod implementation-defined;
13.1/5-- Boolean Type
type C_bool is new Boolean;
14-- Floating Point
15type C_float is digits implementation-defined;
16type double is digits implementation-defined;
17type long_double is digits implementation-defined;
18-- Characters and Strings
19type char is <implementation-defined character type>;
20/1{8652/0060} nul : constant char := implementation-defined;
21function To_C (Item : in Character) return char;
22function To_Ada (Item : in char) return Character;
23/3type char_array is array (size_t range <>) of aliased char
with Pack;
for char_array'Component_Size use CHAR_BIT;
24function Is_Nul_Terminated (Item : in char_array) return Boolean;
25function To_C (Item : in String;
Append_Nul : in Boolean := True)
return char_array;
26function To_Ada (Item : in char_array;
Trim_Nul : in Boolean := True)
return String;
27procedure To_C (Item : in String;
Target : out char_array;
Count : out size_t;
Append_Nul : in Boolean := True);
28procedure 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} type wchar_t is <implementation-defined character type>;
31/1{8652/0060} wide_nul : constant wchar_t := implementation-defined;
32function To_C (Item : in Wide_Character) return wchar_t;
function To_Ada (Item : in wchar_t ) return Wide_Character;
33/3type wchar_array is array (size_t range <>) of aliased wchar_t
with Pack;
34/3This paragraph was deleted.
35function Is_Nul_Terminated (Item : in wchar_array) return Boolean;
36function To_C (Item : in Wide_String;
Append_Nul : in Boolean := True)
return wchar_array;
37function To_Ada (Item : in wchar_array;
Trim_Nul : in Boolean := True)
return Wide_String;
38procedure To_C (Item : in Wide_String;
Target : out wchar_array;
Count : out size_t;
Append_Nul : in Boolean := True);
39procedure To_Ada (Item : in wchar_array;
Target : out Wide_String;
Count : out Natural;
Trim_Nul : in Boolean := True);
39.1/2-- ISO/IEC 10646:2003 compatible types defined by ISO/IEC TR 19769:2004.
39.2/2type char16_t is <implementation-defined character type>;
39.3/2char16_nul : constant char16_t := implementation-defined;
39.4/2function To_C (Item : in Wide_Character) return char16_t;
function To_Ada (Item : in char16_t) return Wide_Character;
39.5/3type char16_array is array (size_t range <>) of aliased char16_t
with Pack;
39.6/3This paragraph was deleted.
39.7/2function 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/2function To_Ada (Item : in char16_array;
Trim_Nul : in Boolean := True)
return Wide_String;
39.9/2procedure To_C (Item : in Wide_String;
Target : out char16_array;
Count : out size_t;
Append_Nul : in Boolean := True);
39.10/2procedure To_Ada (Item : in char16_array;
Target : out Wide_String;
Count : out Natural;
Trim_Nul : in Boolean := True);
39.11/2type char32_t is <implementation-defined character type>;
39.12/2char32_nul : constant char32_t := implementation-defined;
39.13/2function To_C (Item : in Wide_Wide_Character) return char32_t;
function To_Ada (Item : in char32_t) return Wide_Wide_Character;
39.14/3type char32_array is array (size_t range <>) of aliased char32_t
with Pack;
39.15/3This paragraph was deleted.
39.16/2function 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/2function To_Ada (Item : in char32_array;
Trim_Nul : in Boolean := True)
return Wide_Wide_String;
39.18/2procedure To_C (Item : in Wide_Wide_String;
Target : out char32_array;
Count : out size_t;
Append_Nul : in Boolean := True);
39.19/2procedure To_Ada (Item : in char32_array;
Target : out Wide_Wide_String;
Count : out Natural;
Trim_Nul : in Boolean := True);
40Terminator_Error : exception;
41end 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, 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_bool, C_float, and long_double correspond respectively to the C types signed char, unsigned short, unsigned long, unsigned char, bool, 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.
provided that char'Value does not raise an exception; otherwise the result is unspecified.
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;
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;
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;
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);
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;
The result of Is_Nul_Terminated is True if Item contains char32_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;
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);
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.
type char_array is array (size_t range <>) of Char;
{8652/0059} The Convention aspect with convention_identifier C_Pass_By_Copy shall only be specified for a type.
{8652/0059} 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.
{8652/0059} If a type is C_Pass_By_Copy-compatible, then it is also C-compatible.
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.
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} 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
62An implementation may provide additional declarations in the C interface packages.
An implementation is not required to support specifying the Convention aspect with convention_identifier C in the following cases:
- 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 Advice
62.5/3{8652/0060} The constants nul, wide_nul, char16_nul, and char32_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 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} 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} An Ada parameter of a record type T, other than an in parameter of a type of convention C_Pass_By_Copy, is passed as a t* argument to a C function, with the const modifier if the Ada mode is in, where t is the C struct corresponding to the Ada type T.
- An Ada parameter of an array type with component type T is passed as a t* argument to a C function, with the const modifier if the Ada mode is in, 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.
- An Ada parameter of a private type is passed as specified for the full view of the type.
- The rules of correspondence given above for parameters of mode in also apply to the return object of a function.
An implementation should provide unsigned_long_long and long_long as 64-bit modular and signed integer types (respectively) in package Interfaces.C if the C implementation supports unsigned long long and long long as 64-bit types.
Examples
76/5Example of using the Interfaces.C package:
--Calling the C Library Functions strcpy and printf
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--
procedure Strcpy (Target : out C.char_array;
Source : in C.char_array)
with Import => True, Convention => C, External_Name => "strcpy";
79/5-- Call <sdtio.h>printf:
-- C definition of printf: int printf ( const char * format, ... );
-- This function writes the C string pointed by format to the standard output (stdout).
-- If format includes format specifiers (subsequences beginning with %), the additional
-- arguments following format are formatted and inserted in the resulting string
-- replacing their respective specifiers. If the number of arguments does not match
-- the number of format specifiers, or if the types of the arguments do not match
-- the corresponding format specifier, the behaviour is undefined. On success, the
-- printf function returns the total number of characters written to the standard output.
-- If a writing error occurs, a negative number is returned.
79.1/5--
procedure Printf (Format : in C.char_array;
Param1 : in C.char_array;
Param2 : in C.int)
with Import => True, Convention => C_Variadic_1, External_Name => "printf";
80Chars1 : C.char_array(1..20);
Chars2 : C.char_array(1..20);
81begin
Chars2(1..6) := "qwert" & C.nul;
82Strcpy(Chars1, Chars2);
83-- Now Chars1(1..6) = "qwert" & C.Nul
83.1/5Printf("The String=%s, Length=%d", Chars1, Chars1'Length);
84end Test;
Incompatibilities With Ada 95
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
Incompatibilities With Ada 2005
Incompatibilities With Ada 2012
Extensions to Ada 2012
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.Wording Changes from Ada 2012
B.3.1 The Package Interfaces.C.Strings
1/3The 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
2The library package Interfaces.C.Strings has the following declaration:
package Interfaces.C.Strings
with Preelaborate, Nonblocking, Global => in out synchronized is
4type char_array_access is access all char_array;
5/5type chars_ptr is private
with Preelaborable_Initialization ;
6/2type chars_ptr_array is array (size_t range <>) of aliased chars_ptr;
7Null_Ptr : constant chars_ptr;
8function To_Chars_Ptr (Item : in char_array_access;
Nul_Check : in Boolean := False)
return chars_ptr;
9function New_Char_Array (Chars : in char_array) return chars_ptr;
10function New_String (Str : in String) return chars_ptr;
11procedure Free (Item : in out chars_ptr);
12Dereference_Error : exception;
13function Value (Item : in chars_ptr) return char_array;
14function Value (Item : in chars_ptr; Length : in size_t)
return char_array;
15function Value (Item : in chars_ptr) return String;
16function Value (Item : in chars_ptr; Length : in size_t)
return String;
17function Strlen (Item : in chars_ptr) return size_t;
18procedure Update (Item : in chars_ptr;
Offset : in size_t;
Chars : in char_array;
Check : in Boolean := True);
19procedure Update (Item : in chars_ptr;
Offset : in size_t;
Str : in String;
Check : in Boolean := True);
20Update_Error : exception;
21private
... -- not specified by the language
end Interfaces.C.Strings;
pragma Pure.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).
function To_Chars_Ptr (Item : in char_array_access;
Nul_Check : in Boolean := False)
return chars_ptr;
{8652/0061} 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.
function New_Char_Array (Chars : in char_array) return chars_ptr;
This function returns a pointer to an allocated object initialized to Chars(Chars'First .. Index) & nul, where
- Index = Chars'Last if Chars does not contain nul, or
- Index is the smallest size_t value I such that Chars(I+1) = nul.
Storage_Error is propagated if the allocation fails.
function New_String (Str : in String) return chars_ptr;
This function is equivalent to New_Char_Array(To_C(Str)).
procedure Free (Item : in out chars_ptr);
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.
function Value (Item : in chars_ptr) return char_array;
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.
function Value (Item : in chars_ptr; Length : in size_t)
return char_array;
{8652/0062} 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.
function Value (Item : in chars_ptr) return String;
Equivalent to To_Ada(Value(Item), Trim_Nul=>True).
function Value (Item : in chars_ptr; Length : in size_t)
return String;
{8652/0063} Equivalent to To_Ada(Value(Item, Length) & nul, Trim_Nul=>True).
function Strlen (Item : in chars_ptr) return size_t;
Returns Val'Length–1 where Val = Value(Item); propagates Dereference_Error if Item = Null_Ptr.
procedure Update (Item : in chars_ptr;
Offset : in size_t;
Chars : in char_array;
Check : Boolean := True);
{8652/0064} 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:
- Let N = Strlen(Item). If Check is True, then:
- If Offset+Chars'Length>N, propagate Update_Error.
- Otherwise, overwrite the data in the array pointed to by Item, starting at the char at position Offset, with the data in Chars.
- If Check is False, then processing is as above, but with no check that Offset+Chars'Length>N.
procedure Update (Item : in chars_ptr;
Offset : in size_t;
Str : in String;
Check : in Boolean := True);
Equivalent to Update(Item, Offset, To_C(Str, Append_Nul => False), Check).
Erroneous Execution
51Execution 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.
Execution of Free(X) is also erroneous if the chars_ptr X was not returned by New_Char_Array or New_String.
Reading or updating a freed char_array is erroneous.
Execution of Update is erroneous if Check is False and a call with Check equal to True would have propagated Update_Error.
- the returned value (a chars_ptr) is represented as a C “char *” so that it can be passed to C functions;
- the allocated object can be freed by the programmer via a call of Free, rather than by calling a C function.
Inconsistencies With Ada 95
Extensions to Ada 95
pragma Preelaborable_Initialization to type chars_ptr, so that it can be used in preelaborated units.Wording Changes from Ada 95
B.3.2 The Generic Package Interfaces.C.Pointers
1The 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.
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 keeps track of the length.
Static Semantics
3The generic library package Interfaces.C.Pointers has the following declaration:
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
with Preelaborate, Nonblocking, Global => in out synchronized is
5type Pointer is access all Element;
6function Value(Ref : in Pointer;
Terminator : in Element := Default_Terminator)
return Element_Array;
7function Value(Ref : in Pointer;
Length : in ptrdiff_t)
return Element_Array;
8Pointer_Error : exception;
9-- C-style Pointer arithmetic
10/3function "+" (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/3procedure Increment (Ref : in out Pointer)
with Convention => Intrinsic;
procedure Decrement (Ref : in out Pointer)
with Convention => Intrinsic;
12/3This paragraph was deleted.
13function Virtual_Length (Ref : in Pointer;
Terminator : in Element := Default_Terminator)
return ptrdiff_t;
14procedure Copy_Terminated_Array
(Source : in Pointer;
Target : in Pointer;
Limit : in ptrdiff_t := ptrdiff_t'Last;
Terminator : in Element := Default_Terminator);
15procedure Copy_Array (Source : in Pointer;
Target : in Pointer;
Length : in ptrdiff_t);
16end Interfaces.C.Pointers;
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:
- Explicit termination of an array value with Default_Terminator (a special terminator value);
- Programmer-managed length, with Default_Terminator treated simply as a data element.
function Value(Ref : in Pointer;
Terminator : in Element := Default_Terminator)
return Element_Array;
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.
function Value(Ref : in Pointer;
Length : in ptrdiff_t)
return Element_Array;
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.
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.
procedure Increment (Ref : in out Pointer);
Equivalent to Ref := Ref+1.
procedure Decrement (Ref : in out Pointer);
Equivalent to Ref := Ref–1.
function Virtual_Length (Ref : in Pointer;
Terminator : in Element := Default_Terminator)
return ptrdiff_t;
Returns the number of Elements, up to the one just before the first Terminator, in Value(Ref, Terminator).
procedure Copy_Terminated_Array
(Source : in Pointer;
Target : in Pointer;
Limit : in ptrdiff_t := ptrdiff_t'Last;
Terminator : in Element := Default_Terminator);
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.
procedure Copy_Array (Source : in Pointer;
Target : in Pointer;
Length : in ptrdiff_t);
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
35It is erroneous to dereference a Pointer that does not designate an aliased Element.
Execution of Value(Ref, Terminator) is erroneous if Ref does not designate an aliased Element in an Element_Array terminated by Terminator.
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.
Execution of Virtual_Length(Ref, Terminator) is erroneous if Ref does not designate an aliased Element in an Element_Array terminated by Terminator.
Execution of Copy_Terminated_Array(Source, Target, Limit, Terminator) is erroneous in either of the following situations:
- Execution of both Value(Source, Terminator) and Value(Source, Limit) are erroneous, or
- Copying writes past the end of the array containing the Element designated by Target.
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.
Some_Array : Element_Array(0..5) ;
Some_Pointer : Pointer := Some_Array(0)'Access;
Examples
45Example of Interfaces.C.Pointers:
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);
47use type Char_Ptrs.Pointer;
subtype Char_Star is Char_Ptrs.Pointer;
48procedure 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} 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[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/3For a discriminated record type having a variant_part, the following language-defined representation aspect may be specified:
Unchecked_Union
- The type of aspect Unchecked_Union is Boolean. If directly specified, the
aspect_definitionshall be a static expression. If not specified (including by inheritance), the aspect is False.
Legality Rules
Paragraphs 4 and 5 were deleted.
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.
All component subtypes of an unchecked union type shall be C-compatible.
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.
Any name that denotes a discriminant of an object of an unchecked union type shall occur within the declarative region of the type or as the selector_name of an aggregate, and shall not occur within a record_representation_clause.
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.
The completion of an incomplete or private type declaration having a known_discriminant_part shall not be an unchecked union type.
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.
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/2An unchecked union type is eligible for convention C.
All objects of an unchecked union type have the same size.
Discriminants of objects of an unchecked union type are of size zero.
Any check which would require reading a discriminant of an unchecked union object is suppressed (see 11.5). These checks include:
- 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).
- 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.
- The subtype membership check associated with the evaluation of a qualified expression (see 4.7) or an uninitialized allocator (see 4.8).
Dynamic Semantics
20/2A 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.
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.
Program_Error is raised in the following cases:
- Evaluation of the predefined equality operator for an unchecked union type if either of the operands lacks inferable discriminants.
- Evaluation of the predefined equality operator for a type which has a subcomponent of an unchecked union type whose nominal subtype is unconstrained.
- Evaluation of an individual membership test if the
subtype_mark(if any) denotes a constrained unchecked union subtype and the tested_simple_expressionlacks 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.
- Execution of the default implementation of the Write or Read attribute of an unchecked union type.
- 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.
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/2X : T;
Y : Integer := X.F2; -- erroneous
Extensions to Ada 95
Incompatibilities With Ada 2005
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
Wording Changes from Ada 2005
Wording Changes from Ada 2012
subtype_mark.