CBinding.jl

CBinding.jl handles pointers to aggregate types by automatically following them through fields and array elements.

• Dereferencing: Use ptr[] to read the value or ptr[] = val to write to the memory location.
• Automatic Dereferencing: Accessing a field on a pointer (e.g., ptr.field) returns a pointer to that field. You must then use [] to get the actual value.
• Exception: Bitfields are automatically dereferenced because they cannot be referred to via a pointer.

# Assuming 'a' is an existing aggregate
ptr = Libc.malloc(a); 

# ptr.i returns a Cptr, so we use [] to get the value
ptr.i[] 

# Writing to a nested field via pointer
ptr.b.c[2].i[] = 42

Libc.free(ptr)

ptr = Libc.malloc(a);  # allocate a `struct A` as a copy of `a`

ptr.i
ptr.i[]

ptr.b.c[2].i
ptr.b.c[2].i[]
ptr.b.c[2].i[] = 42

Libc.free(ptr)

Use the c"..." (or triple-quoted c"""...""") string macro to input C code. CBinding.jl will automatically create equivalent Julia types, global variable bindings, and function bindings.

You can include C header files directly within the macro to generate bindings for an entire API:

c"""
#include <mylib/header.h>
"""

Note on Naming: To avoid name collisions, generated names are slightly mangled. You should access these bindings using the c"..." macro to indicate they reside in 'C-land'. For example, a C function func is accessed in Julia as c"func".

c"""
struct S;
struct T {
  int i;
  struct S *s;
  struct T *t;
};

extern void func(struct S *s, struct T t);
"""

You can pass a Julia method directly to a C function binding or function pointer that expects a callback. CBinding.jl handles the conversion automatically.

# Assuming a C function: void set_callback(int (*cb)(int, int))

# Simple callback
function myadd(a, b)
    return a + b
end

c"set_callback"(myadd)

# Safer callback with explicit type signatures
function saferadd(a::Cint, b::Cint)::Cint
    return a + b
end

c"set_callback"(saferadd)

function myadd(a, b)  # a callback function to give to C
         return a+b
       end;

> c"set_callback"(myadd)  # that's it!

function saferadd(a::Cint, b::Cint)::Cint  # a safer callback function might require type paranoia
         return a+b
       end;

> c"set_callback"(saferadd)

Before creating bindings, you must set up a compiler context to collect C expressions and specify Clang parser arguments. Use the c command macro (with backticks) at the module scope or in the REPL. This context finds the paths of specified libraries for use in subsequent bindings.

Example of passing compiler flags and library paths:

libpath = find_libpath();
c`-std=c99 -Wall -DGO_FAST=1 -Imylib/include -L$(libpath) -lmylib`

If you encounter issues while generating bindings, try the following:

Note on Mangled Names: If you need to reference a mangled name in the REPL (e.g., for help?), use the var"..." syntax: help?> var"c\"struct Y\"".

Because Julia does not support incomplete types, C types are often represented as abstract types in Julia. This can cause unexpected behavior when using them in collections (e.g., [Y(i=123)] isa Vector{Y} might be false).

Solution: Use the bitstype(T) function to acquire the concrete bits type of any C type when you need to ensure compatibility with arrays or ccall.

# If Y is a C type
[Y(i=123)] isa Vector{Y}        # false
[Y(i=123)] isa Vector{bitstype(Y)} # true

struct X
         i::Cint
       end

const Y = c"""
         struct Y {
           int i;
         };
       """;

[X(123)] isa Vector{X} # true

[Y(i=123)] isa Vector{Y} # false

[Y(i=123)] isa Vector{bitstype(Y)} # true

CBinding.jl preserves type qualifiers like const. For example, a C type int const * is represented in Julia as Cptr{Cconst{Cint}}.

To strip away qualifiers and get the core type, use the unqualifiedtype(T) function:

unqualifiedtype(Cconst{Cint}) === Cint # returns true

You can use the c"..." macro to define C-compatible types or function signatures using existing Julia types. This is useful for passing Julia-defined types into C functions.

Example: Mapping a Julia type to a C pointer and defining a function pointer type:

const c"IntPtr" = Cptr{Cint};

# Define a function pointer type
c"void (*)(IntPtr, IntPtr *, IntPtr[2])" <: Cptr{<:Cfunction}

Global Variables

Bindings to C global variables behave like pointers. You must dereference them using [] to read or write their values. Fields and elements can be followed through the pointer syntax.

Function Bindings

• Direct Call: You can call a bound C function directly: c"func"(arg1, arg2).
• Function Pointers: To obtain a pointer to a bound function (e.g., for use as a callback), use the dereferencing syntax: funcptr = c"func"[]. This returns a Cptr{Cfunction{...}}.

# Call directly
c"func"(Cint(1), Cint(2))

# Get pointer for callbacks
funcptr = c"func"[]
funcptr(Cint(1), Cint(2))

c"func"(Cint(1), Cint(2));  # call the C function directly

funcptr = c"func"[]
Cptr{Cfunction{Int32, Tuple{Int32, Int32}, :cdecl}}(0x00007f8f50722b10)

funcptr(Cint(1), Cint(2));  # call the C function pointer