The core ctypes module.
The main points of interest are the set of functions for describing C types (see types) and the set of functions for accessing C values (see values). The Foreign.foreign function uses C type descriptions to bind external C values.
The type of values representing C types. There are two types associated
with each typ
value: the C type used to store and pass values, and the
corresponding OCaml type. The type parameter indicates the OCaml type, so a
value of type t typ
is used to read and write OCaml values of type t
.
There are various uses of typ
values, including
Value representing the C void type. Void values appear in OCaml as the unit type, so using void in an argument or result type specification produces a function which accepts or returns unit.
Dereferencing a pointer to void is an error, as in C, and will raise IncompleteType.
The scalar types consist of the arithmetic_types and the pointer_types.
The arithmetic types consist of the signed and unsigned integer types (including character types) and the floating types. There are values representing both exact-width integer types (of 8, 16, 32 and 64 bits) and types whose size depend on the platform (signed and unsigned short, int, long, long long).
Value representing an integer type with the same storage requirements as
an OCaml int
.
The type of C-compatible pointer values. A value of type t ptr
can be
used to read and write values of type t
at particular addresses.
A high-level representation of the string type.
On the C side this behaves like char *
; on the OCaml side values read
and written using string are simply native OCaml strings.
To avoid problems with the garbage collector, values passed using string are copied into immovable C-managed storage before being passed to C.
The type of C array values. A value of type t carray
can be used to read
and write array objects in C-managed storage.
The type of Bigarray classes. There are four instances, one for each of the Bigarray submodules.
Construct a function type from a type and an existing function type. This corresponds to prepending a parameter to a C function parameter list. For example,
int @-> ptr void @-> returning float
describes a function type that accepts two arguments -- an integer and a pointer to void -- and returns a float.
The base type of values representing C struct and union types. The
'kind
parameter is a polymorphic variant type indicating whether the type
represents a struct (`Struct
) or a union (`Union
).
The type of values representing C struct or union members (called "fields"
here). A value of type (a, s) field
represents a field of type a
in a
struct or union of type s
.
Construct a new structure type. The type value returned is incomplete and can be updated using [root:(*:*)] until it is passed to seal, at which point the set of fields is fixed.
The type ('_s structure typ
) of the expression returned by the call
structure tag
includes a weak type variable, which can be explicitly
instantiated to ensure that the OCaml values representing different C
structure types have incompatible types. Typical usage is as follows:
type tagname
let tagname : tagname structure typ = structure "tagname"
field ty label ty'
adds a field of type ty'
with label label
to the
structure or union type ty
and returns a field value that can be used to
read and write the field in structure or union instances (e.g. using
getf and setf).
Attempting to add a field to a union type that has been sealed with seal
is an error, and will raise ModifyingSealedType.
seal t
completes the struct or union type t
so that no further fields
can be added. Struct and union types must be sealed before they can be used
in a way that involves their size or alignment; see the documentation for
IncompleteType for further details.
view ~read:r ~write:w t
creates a C type representation t'
which
behaves like t
except that values read using t'
are subsequently
transformed using the function r
and values written using t'
are first
transformed using the function w
.
For example, given suitable definitions of string_of_char_ptr
and
char_ptr_of_string
, the type representation
view ~read:string_of_char_ptr ~write:char_ptr_of_string (ptr char)
can be used to pass OCaml strings directly to and from bound C functions, or to read and write string members in structs and arrays. (In fact, the string type representation is defined in exactly this way.)
The optional argument format_typ
is used by the Ctypes.format_typ and
string_of_typ functions to print the type at the top level and
elsewhere. If format_typ
is not supplied the printer for t
is used
instead.
The type of abstract values. The purpose of the abstract
type is to
represent values whose type varies from platform to platform.
For example, the type pthread_t
is a pointer on some platforms, an
integer on other platforms, and a struct on a third set of platforms. One
way to deal with this kind of situation is to have
possibly-platform-specific code which interrogates the C type in some way
to help determine an appropriate representation. Another way is to use
abstract
, leaving the representation opaque.
(Note, however, that although pthread_t
is a convenient example, since
the type used to implement it varies significantly across platforms, it's
not actually a good match for abstract
, since values of type pthread_t
are passed and returned by value.)
sizeof t
computes the size in bytes of the type t
. The exception
IncompleteType is raised if t
is incomplete.
alignment t
computes the alignment requirements of the type t
. The
exception IncompleteType is raised if t
is incomplete.
!@ p
dereferences the pointer p
. If the reference type is a scalar
type then dereferencing constructs a new value. If the reference type is
an aggregate type then dereferencing returns a value that references the
memory pointed to by p
.
Convert the numeric representation of an address to a pointer
string_from_ptr p ~length
creates a string initialized with the length
characters at address p
.
Raise Invalid_argument "Ctypes.string_from_ptr"
if length
is
negative.
ocaml_string_start s
allows to pass a pointer to the contents of an OCaml
string directly to a C function.
Operations on C arrays.
get a n
returns the n
th element of the zero-indexed array a
. The
semantics for non-scalar types are non-copying, as for [root:(!@)].
If you rebind the CArray
module to Array
then you can also use the
syntax a.(n)
instead of Array.get a n
.
Raise Invalid_argument "index out of bounds"
if n
is outside of the
range 0
to (CArray.length a - 1)
.
set a n v
overwrites the n
th element of the zero-indexed array a
with v
.
If you rebind the CArray
module to Array
then you can also use the
a.(n) <- v
syntax instead of Array.set a n v
.
Raise Invalid_argument "index out of bounds"
if n
is outside of the
range 0
to (CArray.length a - 1)
.
unsafe_get a n
behaves like get a n
except that the check that n
between 0
and (CArray.length a - 1)
is not performed.
unsafe_set a n v
behaves like set a n v
except that the check that
n
between 0
and (CArray.length a - 1)
is not performed.
to_list a
builds a list of the same length as a
such that each
element of the list is the result of reading the corresponding element of
a
.
make t n
creates an n
-length array of type t
. If the optional
argument ?initial
is supplied, it indicates a value that should be
used to initialise every element of the array. The argument ?finalise
,
if present, will be called just before the memory is freed.
Return the address of the first element of the given Bigarray value.
bigarray_of_ptr c dims k p
converts the C pointer p
to a bigarray
value. No copy is made; the bigarray references the memory pointed to by
p
.
Convert a Bigarray value to a C array.
Allocate a fresh, uninitialised structure or union value. The argument
?finalise
, if present, will be called just before the underlying memory is
freed.
setf s f v
overwrites the value of the field f
in the structure or
union s
with v
.
getf s f
retrieves the value of the field f
in the structure or union
s
. The semantics for non-scalar types are non-copying, as for
[root:(!@)].
s @. f
computes the address of the field f
in the structure or union
value s
.
p |-> f
computes the address of the field f
in the structure or union
value pointed to by p
.
addr s
returns the address of the structure or union s
.
coerce t1 t2
returns a coercion function between the types represented
by t1
and t2
. If t1
cannot be coerced to t2
, coerce
raises
Uncoercible.
The following coercions are currently supported:
t
(in either
direction) if there is a coercion between the representation type
underlying the view and t
.t1
is coercible to t2
and t2
is
coercible to t3
, then t1
is directly coercible to t3
.The set of supported coercions is subject to change. Future versions of ctypes may both add new types of coercion and restrict the existing coercions.
coerce_fn f1 f2
returns a coercion function between the function
types represented by f1
and f2
. If f1
cannot be coerced to
f2
, coerce_fn
raises Uncoercible.
A function type f1
may be coerced to another function type f2
if all of the following hold:
f1
and f2
have the same arityf2
may be coerced to the corresponding
argument of f1
f1
may be coerced to the return type of f2
The set of supported coercions is subject to change. Future versions of ctypes may both add new types of coercion and restrict the existing coercions.
An attempt was made to use a feature not currently supported by ctypes. In practice this refers to attempts to use an union, array or abstract type as an argument or return type of a function.
An attempt was made to modify a sealed struct or union type description.
An attempt was made to compute the size or alignment of an incomplete type.
The incomplete types are struct and union types that have not been sealed, and the void type.
It is not permitted to compute the size or alignment requirements of an incomplete type, to use it as a struct or union member, to read or write a value of the type through a pointer or to use it as the referenced type in pointer arithmetic. Additionally, incomplete struct and union types cannot be used as argument or return types.
An attempt was made to coerce between uncoercible types.