Interfacing with C

Sometimes the routine you need is already written in C: a checksum, a numeric kernel, a system call, or a whole library. OCaml reaches it through a foreign function interfaceforeign function interface: A way for code in one language to call functions written in another. In OCaml, you declare a C function with external and link a small C stub that bridges the calling conventions.: you declare the function with external, write a small C stubC stub: A small C function that connects OCaml to a C routine: it reads its OCaml arguments with the runtime's macros, does the work in C, and returns an OCaml value, cooperating with the garbage collector when it allocates. that connects OCaml’s calling conventions to C’s, and let the build compile and link it. The reward is a C function that looks like any other OCaml function; the price is that the stub steps outside the type checker and the garbage collector, so a mistake there is a memory bug, not a type error. This lesson writes three stubs that run, and draws the rules that keep them safe.

An external declaration names a C function

An external declaration binds an OCaml name to a C function. It gives the OCaml type and, as a string, the C function’s name:

(* The external declaration links the OCaml name adler32 to the C
   function tv_adler32. From here on adler32 is an ordinary function
   of type string -> int. *)
external adler32 : string -> int = "tv_adler32"

let () =
  let show s = Printf.printf "adler32 %-11S = 0x%08x\n" s (adler32 s) in
  show "Wikipedia";
  show "";
  show "a";
  show "abc"

/* A C stub for OCaml: the Adler-32 checksum of a string.
   It reads the OCaml string and returns a plain OCaml int, so it
   allocates nothing on the OCaml heap and needs no GC registration. */
#include <caml/mlvalues.h>

CAMLprim value tv_adler32(value s)
{
  const unsigned char *p = (const unsigned char *) String_val(s);
  mlsize_t len = caml_string_length(s);
  unsigned long a = 1, b = 0;
  for (mlsize_t i = 0; i < len; i++) {
    a = (a + p[i]) % 65521;
    b = (b + a) % 65521;
  }
  return Val_long((b << 16) | a);
}

(executable
 (name main)
 (foreign_stubs
  (language c)
  (names adler32_stub)))

From the call’s point of view, adler32 is an ordinary function of type string -> int. The compiler emits a call to tv_adler32; it never sees the C body, so the declared type is a promise it trusts rather than checks. The stub reads the string with String_val and caml_string_length, runs an ordinary C loop, and returns the result tagged as an OCaml int with Val_long. It allocates nothing on the OCaml heap, so the garbage collector cannot interfere. Step through one call as it crosses into C and back:

Build it with dune and run it: the checksum of "Wikipedia" is 0x11e60398, and the empty string gives 0x00000001, because RFC 1950, which defines Adler-32, starts its two sums at 1 and 0.

from session import files, run

# adler32/: a dune executable whose only C file, adler32_stub.c, holds one
# stub, tv_adler32. main.ml declares `external adler32 : string -> int =
# "tv_adler32"` and prints the checksum of four strings. (foreign_stubs
# (language c) (names adler32_stub)) in the dune file compiles and links the
# C file. The checksum of "Wikipedia" is the value printed in the Adler-32
# article, 0x11e60398.
files(
    "adler32/dune-project=dune-project",
    "adler32/dune=dune",
    "adler32/adler32_stub.c=adler32_stub.c",
    "adler32/main.ml=main.ml",
)
run("""
ls
dune build 2>&1
dune exec ./main.exe
""")

$ ls
adler32_stub.c
dune
dune-project
main.ml
$ dune build 2>&1
$ dune exec ./main.exe
adler32 "Wikipedia" = 0x11e60398
adler32 ""          = 0x00000001
adler32 "a"         = 0x00620062
adler32 "abc"       = 0x024d0127

A stub reads OCaml values and returns one

Every argument a stub receives is an OCaml value: one machine word that is either an immediate (an int, a char, a constant constructor, with its low bit set to 1) or a pointer to a heap block (a string, an array, a record, a tuple). A stub never touches that word directly; it uses the runtime’s macros, which the manual’s chapter on interfacing C with OCaml defines. The common ones:

The Adler-32 stub used only the first rows: it read a string and returned an immediate. Because it allocated nothing and held no OCaml value across an allocation, it needed no further ceremony. The moment a stub allocates, a second set of rules begins, and that is where most stub bugs live.

Practise: break the stub on purpose

Work with the adler32/ example, and predict each result before you build:

1. Add show "a\000b" to main.ml, a three-byte string whose middle byte is null. The checksum of those bytes is 0x018800c4. Then replace caml_string_length(s) in the stub by strlen((const char *) String_val(s)) and predict the new value: strlen stops at the null byte, so only the byte a is summed, and the checksum of "a" is 0x00620062.
2. Change the OCaml type of adler32 to bytes -> int and say whether dune build fails, and in which file. The compiler checks every use of adler32 in main.ml against the declared type, so the string passed by show is refused there, while the C file is never consulted.

Then test yourself on the declaration and on reading values:

Interview questions

These questions come up when a team adds its first C binding. Work out your own answer, then open the model answer to compare the reasoning and the fix.

The garbage-collector rules for a stub that allocates, and how to raise an OCaml exception from C Pro: opens with a Pro, Premium or Ultimate pass

Building stubs with dune's foreign_stubs, and the attributes that avoid boxing on numeric calls Pro: opens with a Pro, Premium or Ultimate pass

Binding C without writing stubs: ctypes, and reading an OCaml 5.5 external type Pro: opens with a Pro, Premium or Ultimate pass

Key takeaways

• An external binds an OCaml name to a C function and gives a type the compiler trusts without checking, so a wrong type is a memory bug, not a type error.
• A stub reads its arguments as OCaml values through macros like String_val and Long_val and returns an immediate with Val_long; a stub that only reads and returns needs no further ceremony.
• A string argument is read with String_val and caml_string_length, never with strlen, because an OCaml string may contain null bytes and the block may move.