README

ctypes is a library for binding to C libraries using pure OCaml. The primary aim is to make writing C extensions as straightforward as possible.

The core of ctypes is a set of combinators for describing the structure of C types -- numeric types, arrays, pointers, structs, unions and functions. You can use these combinators to describe the types of the functions that you want to call, then bind directly to those functions -- all without writing or generating any C!

Usage

Suppose you want to bind to the following C functions:

   int sigemptyset(sigset_t *set);   int sigfillset(sigset_t *set);   int sigaddset(sigset_t *set, int signum);   int sigdelset(sigset_t *set, int signum);   int sigismember(const sigset_t *set, int signum);

Using ctypes you can describe the interfaces to these functions as follows:

   let sigemptyset = foreign "sigemptyset" (ptr sigset_t @-> returning int)   let sigfillset = foreign "sigfillset" (ptr sigset_t @-> returning int)   let sigaddset = foreign "sigaddset" (ptr sigset_t @-> int @-> returning int)   let sigdelset = foreign "sigdelset" (ptr sigset_t @-> int @-> returning int)   let sigismember = foreign "sigismember" (ptr sigset_t @-> int @-> returning int)

The names bound by this code have the types you might expect:

   val sigemptyset : sigset_t ptr -> int   val sigfillset : sigset_t ptr -> int   val sigaddset : sigset_t ptr -> int -> int   val sigdelset : sigset_t ptr -> int -> int   val sigismember : sigset_t ptr -> int -> int

That's all there is to it. Unlike theusual way of writing C extensions, there are no C "stub" functions to write, so there's much less opportunity for error.

The documentation and source distribution contain more complex examples, involving structs, unions, arrays, callback functions, and so on, and show how to create and use C values (like instances ofsigset_t ptr) in OCaml.

Links

• Building C libraries in OCaml with the dune ctypes stanza describes how to use ctypes withdune
• Chapter 19: Foreign Function Interface ofReal World OCaml describes ctypes
• Modular Foreign Function Bindings introduces ctypes in the context of theMirage library operating system
• Tutorial
• API documentation
• Mailing list
• Type-safe C bindings using ocaml-ctypes and stub generation introduces theCstubs interface
• Using Cstubs_structs shows how to use theCstubs_structs module to reliably determine data layout
• A modular foreign function interface is a research paper (extending anearlier paper) that presents the design of ctypes
• FAQ

1. conf-libffi>= "2.0.0"
2. conf-pkg-config
3. dune-configurator
4. ctypes= version
5. ocaml>= "4.03.0"
6. dune>= "2.9"

1. odocwith-doc
2. conf-ftswith-test & os != "win32"
3. stdlib-shimswith-test
4. conf-ncurseswith-test
5. ounit2with-test
6. lwtwith-test & >= "2.4.7"
7. integerswith-test & >= "0.2.2"

1. argon2
2. arrayjit
3. async_ssl
4. bimage-unix
5. bls12-381= "0.3.15"
6. bls12-381-legacy< "0.4.4"
7. bls12-381-unix< "1.0.2"
8. camlkit-base
9. cf
10. checked_oint< "0.4.1"
11. cmark
12. cmarker
13. corosync
14. ctypes< "0.21.1"
15. ctypes-zarith
16. cudajit
17. directories< "0.3"
18. echo
19. extism
20. flock
21. gccjit
22. gdal
23. gobject-introspection
24. gpiod
25. gr
26. guile
27. hacl-star-raw< "0.4.4"
28. hardcaml_c
29. hardcaml_verilator
30. hdr_histogram
31. imguiml
32. libbpf_maps
33. libdash
34. libirmin
35. libudev
36. lilv
37. llama-cpp-ocaml
38. lmdb< "1.0"
39. lp-glpk< "0.4.0"
40. lp-gurobi
41. memtrace_viewer< "v0.15.0"
42. mmdb
43. mpg123
44. netlink
45. nx
46. ocephes
47. octez-l2-libs
48. opasswd
49. opencc< "transition"
50. opencc0
51. opencc1
52. opencc1_1
53. orocksdb
54. osx-cf
55. osx-secure-transport
56. pari
57. pari-bindings
58. pg_query
59. pkcs11-driver
60. pkcs11-rev
61. portaudio_c_bindings
62. portmidi
63. posix-getopt< "2.0.0"
64. py
65. qcstm>= "0.1.1"
66. reed-solomon-erasure
67. rune
68. sarek
69. sattools
70. sodium< "0.6.0"
71. spoc
72. srt
73. stk_iconv
74. swipl
75. tensorflow
76. tezos-wasmer
77. tgls
78. torch
79. tsdl
80. tsdl-image
81. tsdl-mixer
82. tsdl-ttf
83. unix-type-representations< "0.1.1"
84. wasmer
85. wasmtime
86. yara
87. yices2_bindings

None