[Home] [Prev] [Next] [Index]
B.3 Interfacing with C
B.3 Interfacing with C
- 1
- The facilities relevant to interfacing with the C language are the package Interfaces.C and its children; and support for the Import, Export, and Convention pragmas with convention_identifier C.
- 2
- 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
- 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
- nul : constant char := char'First;
- 21
- function To_C (Item : in Character) return char;
- 22
- function To_Ada (Item : in char) return Character;
- 23
- type char_array is array (size_t range <>) of aliased char;
pragma Pack(char_array);
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
- type wchar_t is implementation-defined;
- 31
- wide_nul : constant wchar_t := wchar_t'First;
- 32
- function To_C (Item : in Wide_Character) return wchar_t;
function To_Ada (Item : in wchar_t ) return Wide_Character;
- 33
- type wchar_array is array (size_t range <>) of aliased wchar_t;
- 34
- pragma Pack(wchar_array);
- 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);
- 40
- Terminator_Error : exception;
- 41
- end Interfaces.C;
- 42
- Each of the types declared in Interfaces.C is C-compatible.
- 43
- 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.
- 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.
- 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
- 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.
- 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.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.
- Implementation Requirements
- 61
- An implementation shall support pragma Convention with a C convention_identifier for a C-eligible type (see B.1)
- Implementation Permissions
- 62
- An implementation may provide additional declarations in the C interface packages.
- Implementation Advice
- 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.
- 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.a
- Change: Changed "scalar" to "elementary" in second sentence; the by-copy types are elementary, not just scalars.
- 69 ·
- An Ada parameter of a record type T, of any mode, 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.
- NOTES
- 72 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.
- 73 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).
- 74 11
- There is no explicit support for C's union types. Unchecked conversions can be used to obtain the effect of C unions.
- 75 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
- 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
- -- 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);
- 79
- pragma Import(C, Strcpy, "strcpy");
- 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;
B.3.1 The Package Interfaces.C.Strings
- 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 pragma Import(C,...) has been applied, 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
- type chars_ptr is private;
- 6
- type chars_ptr_array is array (size_t range <>) of 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
- If Item is null, then To_Chars_Ptr returns Null_Ptr. Otherwise, if Nul_Check is True and Item.all does not contain nul, then the function propagates Terminator_Error; if Nul_Check is True and Item.all does contain nul, 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.
-
- 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
- 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
- If Item = Null_Ptr then Value(Item) propagates Dereference_Error. Otherwise Value returns the shorter of two arrays: the first Length chars pointed to by Item, and Value(Item). The lower bound of the result is 0.
- 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
- Equivalent to To_Ada(Value(Item, Length), 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
- 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
- Equivalent to Update(Item, Offset, To_C(Str), Check).
- 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 13
- 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.
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
- function "+" (Left : in Pointer; Right : in ptrdiff_t) return Pointer;
function "+" (Left : in ptrdiff_t; Right : in Pointer) return Pointer;
function "-" (Left : in Pointer; Right : in ptrdiff_t) return Pointer;
function "-" (Left : in Pointer; Right : in Pointer) return ptrdiff_t;
- 11
- procedure Increment (Ref : in out Pointer);
procedure Decrement (Ref : in out Pointer);
- 12
- pragma Convention (Intrinsic, "+");
pragma Convention (Intrinsic, "-");
pragma Convention (Intrinsic, Increment);
pragma Convention (Intrinsic, Decrement);
- 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 14
- 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
- loop
Element := Source_Temp_Ptr.all;
Target_Temp_Ptr.all := Element;
exit when Element = C.nul;
Char_Ptrs.Increment(Target_Temp_Ptr);
Char_Ptrs.Increment(Source_Temp_Ptr);
end loop;
end Strcpy;
begin
...
end Test_Pointers;
[Home] [Prev] [Next] [Index]
documentation@rational.com
Copyright © 1993-1998, Rational Software Corporation. All rights
reserved.