Module Ctypes

module Ctypes: sig .. end

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 representing C values). The Foreign.foreign function uses C type descriptions to bind external C values.

Pointer types

type ('a, 'b) pointer = ('a, 'b) Ctypes_static.pointer

The type of pointer values. A value of type ('a, [`C]) pointer contains a C-compatible pointer, and a value of type ('a, [`OCaml]) pointer contains a pointer to a value that can be moved by OCaml runtime.

C-compatible pointers

type 'a ptr = ('a, [ `C ]) pointer

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.

type 'a ocaml = 'a Ctypes_static.ocaml

The type of pointer values pointing directly into OCaml values. Pointers of this type should never be captured by external code. In particular, functions accepting 'a ocaml pointers must not invoke any OCaml code.

C array types

type 'a carray = 'a Ctypes_static.carray

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.

Bigarray types

type 'a bigarray_class = 'a Ctypes_static.bigarray_class

The type of Bigarray classes. There are four instances, one for each of the Bigarray submodules.

val genarray : < ba_repr : 'b; bigarray : ('a, 'b, 'l) Bigarray.Genarray.t;
         carray : 'a carray; dims : int array; element : 'a; layout : 'l >
       bigarray_class

The class of Bigarray.Genarray.t values

val array1 : < ba_repr : 'b; bigarray : ('a, 'b, 'l) Bigarray.Array1.t;
         carray : 'a carray; dims : int; element : 'a; layout : 'l >
       bigarray_class

The class of Bigarray.Array1.t values

val array2 : < ba_repr : 'b; bigarray : ('a, 'b, 'l) Bigarray.Array2.t;
         carray : 'a carray carray; dims : int * int; element : 'a;
         layout : 'l >
       bigarray_class

The class of Bigarray.Array2.t values

val array3 : < ba_repr : 'b; bigarray : ('a, 'b, 'l) Bigarray.Array3.t;
         carray : 'a carray carray carray;
         dims : int * int * int; element : 'a; layout : 'l >
       bigarray_class

The class of Bigarray.Array3.t values

Struct and union types

type ('a, 'kind) structured = ('a, 'kind) Ctypes_static.structured

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

type 'a structure = ('a, [ `Struct ]) structured

The type of values representing C struct types.

type 'a union = ('a, [ `Union ]) structured

The type of values representing C union types.

type ('a, 't) field = ('a, 't) Ctypes_static.field

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.

type 'a abstract = 'a Ctypes_static.abstract

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

include Ctypes_types.TYPE

Operations on types

val sizeof : 'a typ -> int

sizeof t computes the size in bytes of the type t. The exception Ctypes.IncompleteType is raised if t is incomplete.

val alignment : 'a typ -> int

alignment t computes the alignment requirements of the type t. The exception Ctypes.IncompleteType is raised if t is incomplete.

val format_typ : ?name:string -> Format.formatter -> 'a typ -> unit

Pretty-print a C representation of the type to the specified formatter.

val format_fn : ?name:string -> Format.formatter -> 'a fn -> unit

Pretty-print a C representation of the function type to the specified formatter.

val string_of_typ : ?name:string -> 'a typ -> string

Return a C representation of the type.

val string_of_fn : ?name:string -> 'a fn -> string

Return a C representation of the function type.

Values representing C values

val format : 'a typ -> Format.formatter -> 'a -> unit

Pretty-print a representation of the C value to the specified formatter.

val string_of : 'a typ -> 'a -> string

Return a string representation of the C value.

Pointer values

val null : unit ptr

A null pointer.

val (!@) : 'a ptr -> 'a

!@ 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.

val (<-@) : 'a ptr -> 'a -> unit

p <-@ v writes the value v to the address p.

val (+@) : ('a, 'b) pointer -> int -> ('a, 'b) pointer

If p is a pointer to an array element then p +@ n computes the address of the nth next element.

val (-@) : ('a, 'b) pointer -> int -> ('a, 'b) pointer

If p is a pointer to an array element then p -@ n computes the address of the nth previous element.

val ptr_diff : ('a, 'b) pointer -> ('a, 'b) pointer -> int

ptr_diff p q computes q - p. As in C, both p and q must point into the same array, and the result value is the difference of the subscripts of the two array elements.

val from_voidp : 'a typ -> unit ptr -> 'a ptr

Conversion from void *.

val to_voidp : 'a ptr -> unit ptr

Conversion to void *.

val allocate : ?finalise:('a ptr -> unit) -> 'a typ -> 'a -> 'a ptr

allocate t v allocates a fresh value of type t, initialises it with v and returns its address. The argument ?finalise, if present, will be called just before the memory is freed. The value will be automatically freed after no references to the pointer remain within the calling OCaml program.

val allocate_n : ?finalise:('a ptr -> unit) -> 'a typ -> count:int -> 'a ptr

allocate_n t ~count:n allocates a fresh array with element type t and length n, and returns its address. The argument ?finalise, if present, will be called just before the memory is freed. The array will be automatically freed after no references to the pointer remain within the calling OCaml program. The memory is allocated with libc's calloc and is guaranteed to be zero-filled.

val ptr_compare : 'a ptr -> 'a ptr -> int

If p and q are pointers to elements i and j of the same array then ptr_compare p q compares the indexes of the elements. The result is negative if i is less than j, positive if i is greater than j, and zero if i and j are equal.

val is_null : 'a ptr -> bool

is_null p is true when p is a null pointer.

val reference_type : 'a ptr -> 'a typ

Retrieve the reference type of a pointer.

val ptr_of_raw_address : nativeint -> unit ptr

Convert the numeric representation of an address to a pointer

val funptr_of_raw_address : nativeint -> (unit -> unit) Ctypes_static.static_funptr

Convert the numeric representation of an address to a function pointer

val raw_address_of_ptr : unit ptr -> nativeint

raw_address_of_ptr p returns the numeric representation of p.

Note that the return value remains valid only as long as the pointed-to object is alive. If p is a managed object (e.g. a value returned by Ctypes.make) then unless the caller retains a reference to p, the object may be collected, invalidating the returned address.

val string_from_ptr : char ptr -> length:int -> string

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.

val ocaml_string_start : string -> string ocaml

ocaml_string_start s allows to pass a pointer to the contents of an OCaml string directly to a C function.

val ocaml_bytes_start : Bytes.t -> Bytes.t ocaml

ocaml_bytes_start s allows to pass a pointer to the contents of an OCaml byte array directly to a C function.

Array values

C array values

module CArray: sig .. end

Operations on C arrays.

Bigarray values

val bigarray_start : < ba_repr : 'c; bigarray : 'b; carray : 'd; dims : 'e; element : 'a;
         layout : 'l >
       bigarray_class -> 'b -> 'a ptr

Return the address of the first element of the given Bigarray value.

val bigarray_of_ptr : < ba_repr : 'f; bigarray : 'b; carray : 'c; dims : 'i; element : 'a;
         layout : Bigarray.c_layout >
       bigarray_class -> 'i -> ('a, 'f) Bigarray.kind -> 'a ptr -> 'b

bigarray_of_ptr c dims k p converts the C pointer p to a C-layout bigarray value. No copy is made; the bigarray references the memory pointed to by p.

val fortran_bigarray_of_ptr : < ba_repr : 'f; bigarray : 'b; carray : 'c; dims : 'i; element : 'a;
         layout : Bigarray.fortran_layout >
       bigarray_class -> 'i -> ('a, 'f) Bigarray.kind -> 'a ptr -> 'b

fortran_bigarray_of_ptr c dims k p converts the C pointer p to a Fortran-layout bigarray value. No copy is made; the bigarray references the memory pointed to by p.

val array_of_bigarray : < ba_repr : 'a; bigarray : 'b; carray : 'c; dims : 'd; element : 'e;
         layout : Bigarray.c_layout >
       bigarray_class -> 'b -> 'c

array_of_bigarray c b converts the bigarray value b to a value of type Ctypes.CArray.t. No copy is made; the result occupies the same memory as b.

Convert a Bigarray value to a C array.

val bigarray_of_array : < ba_repr : 'f; bigarray : 'b; carray : 'c carray; dims : 'i;
         element : 'a; layout : Bigarray.c_layout >
       bigarray_class -> ('a, 'f) Bigarray.kind -> 'c carray -> 'b

bigarray_of_array c k a converts the Ctypes.CArray.t value a to a C-layout bigarray value. No copy is made; the result occupies the same memory as a.

Struct and union values

val make : ?finalise:(('a, 'b) structured -> unit) ->
       ('a, 'b) structured typ -> ('a, 'b) structured

Allocate a fresh, uninitialised structure or union value. The argument ?finalise, if present, will be called just before the underlying memory is freed.

val setf : ('b, 'c) structured ->
       ('a, ('b, 'c) structured) field -> 'a -> unit

setf s f v overwrites the value of the field f in the structure or union s with v.

val getf : ('b, 'c) structured ->
       ('a, ('b, 'c) structured) field -> 'a

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 Ctypes.(!@).

val (@.) : ('b, 'c) structured ->
       ('a, ('b, 'c) structured) field -> 'a ptr

s @. f computes the address of the field f in the structure or union value s.

val (|->) : ('b, 'c) structured ptr ->
       ('a, ('b, 'c) structured) field -> 'a ptr

p |-> f computes the address of the field f in the structure or union value pointed to by p.

val offsetof : ('a, 'b structure) field -> int

offsetof f returns the offset, in bytes, of the field f from the beginning of the associated struct type.

val field_type : ('a, 'b) field -> 'a typ

field_type f returns the type of the field f.

val field_name : ('a, 'b) field -> string

field_name f returns the name of the field f.

val addr : ('a, 'b) structured -> ('a, 'b) structured ptr

addr s returns the address of the structure or union s.

Coercions

val coerce : 'a typ -> 'b typ -> 'a -> 'b

coerce t1 t2 returns a coercion function between the types represented by t1 and t2. If t1 cannot be coerced to t2, coerce raises Ctypes.Uncoercible.

The following coercions are currently supported:

All function and object pointer types are intercoercible.
Any type may be coerced to void
There is a coercion between a view and another type t (in either direction) if there is a coercion between the representation type underlying the view and t.
Coercion is transitive: if 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.

val coerce_fn : 'a fn -> 'b fn -> 'a -> 'b

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 Ctypes.Uncoercible.

A function type f1 may be coerced to another function type f2 if all of the following hold:

the C types described by f1 and f2 have the same arity

each argument of f2 may be coerced to the corresponding argument of f1

the return type of 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.

module type FOREIGN = sig .. end

Foreign function binding interface.

module Root: sig .. end

Registration of OCaml values as roots

Exceptions

exception Unsupported of string

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.

exception ModifyingSealedType of string

An attempt was made to modify a sealed struct or union type description.

exception IncompleteType

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.

type uncoercible_info

exception Uncoercible of uncoercible_info

An attempt was made to coerce between uncoercible types.