package cstruct

All checked builds pass
  1. Overview
  2. Docs
Access C-like structures directly from OCaml

Install 

dune-project
 Dependency

github.com Readme Changelog ISC License Edit opam file Versions (10)

Authors

  1. A
    Anil Madhavapeddy
  2. R
    Richard Mortier
  3. T
    Thomas Gazagnaire
  4. P
    Pierre Chambart
  5. D
    David Kaloper
  6. J
    Jeremy Yallop
  7. D
    David Scott
  8. M
    Mindy Preston
  9. T
    Thomas Leonard
  10. A
    Anton Kochkov
  11. E
    Etienne Millon

Maintainers

  1. A
    anil@recoil.org

Sources

cstruct-6.3.0.tbz
sha256=956b249ddfb55fd23584c1767af28f6487033d364888217a14275d898ebd7754
sha512=71a503c7017f2d143ec8af2b8f132d1f59a0526ee4602b9a3e307e904bc18867755f87f445e4a49d995c7ca0002adfc2e3dae2f5fa6e22fb71fe85db774dede1

Description

Cstruct is a library and syntax extension to make it easier to access C-like structures directly from OCaml. It supports both reading and writing to these structures, and they are accessed via the Bigarray module.

Tags

org:mirage org:ocamllabs

Added to opam-repository:

README

Cstruct - access C-like structures directly from OCaml

Cstruct is a library and syntax extension to make it easier to access C-like structures directly from OCaml. It supports both reading and writing to these structures, and they are accessed via the Bigarray module.

Installation

This repository provides several packages that can be installed via the opam package manager:

  • cstruct: the core Cstruct library
  • cstruct-sexp: serialisers into s-expression format of Cstructs
  • cstruct-unix: provide Unix variations of the read/write functions using file descriptors
  • cstruct-async: provide Async Pipe and Bigstring support
  • cstruct-lwt: provide Lwt variants of read/write functions
  • ppx_cstruct: a PPX syntax extension (see below)

The libraries depend on OCaml version 4.08.0 and later, since it provides a ppx extension point. The old camlp4 syntax extension is nolonger available; the last cstruct release which contained it was v1.9.0.

Local development

You can build the library via dune, using make or dune build directly. Since everything is built via dune, you can also place this repository within a wider dune workspace in order to make local modifications across repositories.

Documentation

A documentation of the last version of cstruct is available here.

Usage

PPX

The PPX processor is used by passing the OCaml source code through the ppx_cstruct binary. An example pcap description is:

[%%cstruct
type pcap_header = {
  magic_number: uint32_t;   (* magic number *)
  version_major: uint16_t;  (* major version number *)
  version_minor: uint16_t;  (* minor version number *)
  thiszone: uint32_t;       (* GMT to local correction *)
  sigfigs: uint32_t;        (* accuracy of timestamps *)
  snaplen: uint32_t;        (* max length of captured packets, in octets *)
  network: uint32_t;        (* data link type *)
} [@@little_endian]]

[%%cstruct
type pcap_packet = {
  ts_sec: uint32_t;         (* timestamp seconds *)
  ts_usec: uint32_t;        (* timestamp microseconds *)
  incl_len: uint32_t;       (* number of octets of packet saved in file *)
  orig_len: uint32_t;       (* actual length of packet *)
} [@@little_endian]]

[%%cstruct
type ethernet = {
  dst: uint8_t [@len 6];
  src: uint8_t [@len 6];
  ethertype: uint16_t;
} [@@big_endian]]

[%%cstruct
type ipv4 = {
  hlen_version: uint8_t;
  tos: uint8_t;
  len: uint16_t;
  id: uint16_t;
  off: uint16_t;
  ttl: uint8_t;
  proto: uint8_t;
  csum: uint16_t;
  src: uint8_t [@len 4];
  dst: uint8_t [@len 4];
} [@@big_endian]]

This auto-generates generates functions of the form below in the ml file:

let sizeof_pcap_packet = 16
let get_pcap_packet_ts_sec v = Cstruct.LE.get_uint32 v 0
let set_pcap_packet_ts_sec v x = Cstruct.LE.set_uint32 v 0 x
let get_pcap_packet_ts_usec v = Cstruct.LE.get_uint32 v 4
let set_pcap_packet_ts_usec v x = Cstruct.LE.set_uint32 v 4 x
let get_pcap_packet_incl_len v = Cstruct.LE.get_uint32 v 8
let set_pcap_packet_incl_len v x = Cstruct.LE.set_uint32 v 8 x
let get_pcap_packet_orig_len v = Cstruct.LE.get_uint32 v 12
let set_pcap_packet_orig_len v x = Cstruct.LE.set_uint32 v 12 x

let sizeof_ethernet = 14
let get_ethernet_dst src = Cstruct.sub src 0 6
let copy_ethernet_dst src = Cstruct.copy src 0 6
let set_ethernet_dst src srcoff dst =
  Cstruct.blit_from_string src srcoff dst 0 6
let blit_ethernet_dst src srcoff dst = Cstruct.blit src srcoff dst 0 6
let get_ethernet_src src = Cstruct.sub src 6 6
let copy_ethernet_src src = Cstruct.copy src 6 6
let set_ethernet_src src srcoff dst =
  Cstruct.blit_from_string src srcoff dst 6 6
let blit_ethernet_src src srcoff dst = Cstruct.blit src srcoff dst 6 6
let get_ethernet_ethertype v = Cstruct.BE.get_uint16 v 12
let set_ethernet_ethertype v x = Cstruct.BE.set_uint16 v 12 x

The mli file will have signatures of this form:

val sizeof_pcap_packet : int
val get_pcap_packet_ts_sec : Cstruct.t -> Cstruct.uint32
val set_pcap_packet_ts_sec : Cstruct.t -> Cstruct.uint32 -> unit
val get_pcap_packet_ts_usec : Cstruct.t -> Cstruct.uint32
val set_pcap_packet_ts_usec : Cstruct.t -> Cstruct.uint32 -> unit
val get_pcap_packet_incl_len : Cstruct.t -> Cstruct.uint32
val set_pcap_packet_incl_len : Cstruct.t -> Cstruct.uint32 -> unit
val get_pcap_packet_orig_len : Cstruct.t -> Cstruct.uint32
val set_pcap_packet_orig_len : Cstruct.t -> Cstruct.uint32 -> unit
val hexdump_pcap_packet_to_buffer : Buffer.t -> pcap_packet -> unit
val hexdump_pcap_packet : Cstruct.t -> unit

val sizeof_ethernet : int
val get_ethernet_dst : Cstruct.t -> Cstruct.t
val copy_ethernet_dst : Cstruct.t -> string
val set_ethernet_dst : string -> int -> Cstruct.t -> unit
val blit_ethernet_dst : Cstruct.t -> int -> Cstruct.t -> unit
val get_ethernet_src : Cstruct.t -> Cstruct.t
val copy_ethernet_src : Cstruct.t -> string
val set_ethernet_src : string -> int -> Cstruct.t -> unit
val blit_ethernet_src : Cstruct.t -> int -> Cstruct.t -> unit
val get_ethernet_ethertype : Cstruct.t -> Cstruct.uint16
val set_ethernet_ethertype : Cstruct.t -> Cstruct.uint16 -> unit
val hexdump_ethernet_to_buffer : Buffer.t -> Cstruct.t -> unit
val hexdump_ethernet : Cstruct.t -> unit

The hexdump functions above are convenient pretty-printing functions to help you debug, and aren't intended to be high performance.

You can also declare C-like enums:

[%%cenum
type foo32 =
  | ONE32
  | TWO32 [@id 0xfffffffel]
  | THREE32
  [@@uint32_t]
]

[%%cenum
type bar16 =
  | ONE [@id 1]
  | TWO
  | FOUR [@id 4]
  | FIVE
  [@@uint16_t]
]

This generates signatures of the form:

type foo32 = | ONE32 | TWO32 | THREE32
val int_to_foo32 : int32 -> foo32 option
val foo32_to_int : foo32 -> int32
val foo32_to_string : foo32 -> string
val string_to_foo32 : string -> foo32 option
val compare_foo32 : foo32 -> foo32 -> int
type bar16 = | ONE | TWO | FOUR | FIVE
val int_to_bar16 : int -> bar16 option
val bar16_to_int : bar16 -> int
val bar16_to_string : bar16 -> string
val string_to_bar16 : string -> bar16 option
val compare_bar16 : bar16 -> bar16 -> int

Comparisons will be done relatively to the constructor ids.

You can also add a (sexp) decorator to output s-expression convertors for use with the sexplib library.

[%%cenum
type foo64 =
  | ONE64
  | TWO64
  | THREE64
  [@@uint64_t] [@@sexp]
]

And sexp_of_foo64 and foo64_of_sexp functions will also be available. The representation of the Sexp is the string representation of the enum.

If you do use the sexp decorator, then you will also need to add sexplib to the dependency list for your package (both in the dune file and the opam file).

Please see the ppx_test/ directory for more in-depth examples.

Dependencies (3)

  1. fmt >= "0.8.9"
  2. dune >= "3.17"
  3. ocaml >= "4.08.0"

Dev Dependencies (2)

  1. crowbar with-test & >= "0.2"
  2. alcotest with-test

Optional Dependencies

None

  1. a2a-client
  2. albatross >= "1.4.3" & < "2.3.0"
  3. arp
  4. asn1-combinators = "0.2.6"
  5. async_unix >= "v0.17.0"
  6. awa < "0.6.0"
  7. awa-mirage
  8. bin >= "0.1.0"
  9. bip32
  10. builder < "0.4.0"
  11. builder-web < "0.2.0"
  12. capnp-rpc-net
  13. capnp-rpc-unix >= "2.1"
  14. carton >= "0.4.3" & < "1.0.0"
  15. carton-git
  16. carton-lwt < "1.0.0"
  17. certify < "0.3.3"
  18. chamelon
  19. charrua
  20. charrua-client
  21. charrua-server
  22. coap
  23. coap-core
  24. coap-server-lwt
  25. cohttp-mirage
  26. colombe < "0.2.0"
  27. conduit-mirage
  28. conex < "0.10.0"
  29. conex-mirage-crypto < "1.0.0"
  30. console-eio
  31. cowabloga
  32. crc
  33. cstruct-async >= "6.3.0"
  34. cstruct-lwt >= "6.3.0"
  35. cstruct-sexp >= "6.3.0"
  36. cstruct-unix >= "6.3.0"
  37. current-albatross-deployer
  38. current_git >= "0.6.2"
  39. current_github
  40. current_web
  41. dbase4 < "0.2.0"
  42. depyt
  43. dns >= "6.3.0" & < "9.1.0"
  44. dns-cli < "9.1.0"
  45. dns-client < "7.0.3"
  46. dns-forward
  47. dns-mirage
  48. dns-server
  49. dns-stub
  50. dns-tsig < "9.1.0"
  51. dnssd
  52. dnssec < "9.1.0"
  53. dream
  54. eio
  55. eqaf >= "0.8" & < "0.10"
  56. eqaf-cstruct
  57. ethernet
  58. fat-filesystem = "0.13.0" | >= "0.15.0"
  59. frenetic
  60. geojsone >= "0.2.0"
  61. git < "3.6.0" | >= "3.15.0"
  62. git-cohttp
  63. git-cohttp-unix
  64. git-kv >= "0.2.0"
  65. git-mirage
  66. git-unix >= "3.2.0"
  67. github-hooks
  68. gluten-mirage < "0.5.2"
  69. gpt
  70. granary
  71. h2-mirage
  72. hacl-star >= "0.7.0"
  73. hex >= "1.4.0"
  74. hkdf
  75. http-multipart-formdata >= "3.1.0"
  76. httpun-mirage
  77. httpun-ws-mirage
  78. hvsock
  79. intel_hex < "0.4"
  80. io-page
  81. io-page-unix
  82. ipaddr-cstruct
  83. irmin-git
  84. irmin-indexeddb
  85. jose < "0.10.0"
  86. k7
  87. kafka-eio
  88. key-parsers >= "1.2.1"
  89. launchd
  90. learn-ocaml-client
  91. ledgerwallet >= "0.2.1"
  92. letsencrypt < "1.0.0"
  93. letsencrypt-app < "1.0.0"
  94. lt-code
  95. macaddr-cstruct
  96. mbr-format
  97. memtrace_viewer < "v0.15.0"
  98. miaou-serve
  99. mimic >= "0.0.4"
  100. mirage-block >= "2.0.1"
  101. mirage-block-ccm
  102. mirage-block-combinators >= "3.0.2"
  103. mirage-block-ramdisk
  104. mirage-block-solo5
  105. mirage-block-unikraft
  106. mirage-block-unix != "2.12.1"
  107. mirage-block-xen
  108. mirage-btrees
  109. mirage-channel >= "4.1.0"
  110. mirage-channel-lwt
  111. mirage-conduit
  112. mirage-console-lwt
  113. mirage-crypto >= "0.10.7" & < "1.1.0"
  114. mirage-crypto-ec < "1.1.0"
  115. mirage-crypto-pk < "1.1.0"
  116. mirage-crypto-rng < "1.1.0"
  117. mirage-crypto-rng-eio
  118. mirage-crypto-rng-mirage < "1.1.0"
  119. mirage-flow >= "3.0.0"
  120. mirage-flow-combinators
  121. mirage-flow-unix
  122. mirage-fs >= "4.0.0"
  123. mirage-fs-lwt
  124. mirage-kv-lwt
  125. mirage-kv-unix
  126. mirage-nat
  127. mirage-net >= "4.0.0"
  128. mirage-net-lwt
  129. mirage-net-macosx
  130. mirage-net-solo5
  131. mirage-net-unikraft
  132. mirage-net-unix
  133. mirage-net-xen
  134. mirage-profile
  135. mirage-protocols >= "7.0.0"
  136. mirage-protocols-lwt
  137. mirage-qubes
  138. mirage-random
  139. mirage-solo5 < "0.10.0"
  140. mirage-stack-lwt
  141. mirage-tc
  142. mirage-types-lwt
  143. mirage-vnetif
  144. mirage-xen
  145. mnet-dhcp
  146. monorobot
  147. multihash
  148. nbd >= "4.0.3"
  149. neodriver_eio
  150. ohttp-cohttp-eio
  151. oneffs
  152. otr < "1.0.0"
  153. oxbow
  154. paf
  155. pbkdf
  156. pcap-format >= "0.5.2"
  157. pf-qubes
  158. plebeia
  159. plist-xml >= "0.4.0" & < "0.5.1"
  160. ppx_cstruct >= "6.3.0"
  161. protocol-9p >= "2.0.2"
  162. protocol-9p-tool = "2.0.2"
  163. protocol-9p-unix = "0.11.3" | >= "2.0.2"
  164. proton
  165. qcow
  166. qcow-tool
  167. qcow-types
  168. randomconv < "0.2.0"
  169. rawlink >= "1.2"
  170. reparse >= "3.0.0"
  171. reparse-lwt
  172. reparse-lwt-unix
  173. rfc6287 < "1.0.4"
  174. rio
  175. riot = "0.0.7"
  176. salsa20 != "1.1.0"
  177. salsa20-core = "1.1.0"
  178. scrypt-kdf
  179. secp256k1-internal >= "0.3.1"
  180. sendmail >= "0.5.0"
  181. shared-block-ring
  182. shared-memory-ring
  183. shared-memory-ring-lwt
  184. sihl >= "3.0.0"
  185. slack
  186. solo5-elftool < "0.4.0"
  187. spoke >= "0.0.4"
  188. ssh-agent != "0.3.0" & < "0.5.0"
  189. swapfs
  190. tar < "3.3.0"
  191. tar-mirage
  192. tar-unix < "3.3.0"
  193. tcpip >= "7.1.2"
  194. tls >= "0.12.8" & < "1.0.4"
  195. tls-liquidsoap
  196. uecc
  197. uring
  198. utcp
  199. valkey
  200. vchan
  201. vchan-unix
  202. vchan-xen
  203. verdict
  204. vhd-format >= "0.12.0" & < "0.12.2" | >= "0.13.0"
  205. vhd-format-lwt >= "0.13.0"
  206. vmnet
  207. wayland >= "1.0"
  208. webauthn < "0.2.0"
  209. wol
  210. x509 >= "0.14.1" & < "1.0.6"
  211. xen-gnt
  212. yocaml_git >= "2.0.0"

Conflicts (1)

  1. js_of_ocaml < "3.5.0"

Build status

Results of building cstruct with each compiler on check.ci.ocaml.org, run of against opam-repository 8a77e58. All results for this package.

Each result links to its build log. To keep crawlers from overloading the site, build logs require a GitHub sign-in (see ocurrent/opam-health-check). On your first log, GitHub asks you to “Authorize opam-health-check”, the OCurrent app that runs these checks; it sees only your public profile, not your repositories. The sign-in lasts 30 days.

Version OCaml 4.11 OCaml 4.14 OCaml 5.2 OCaml 5.4 OCaml 5.5
6.3.0 (this version) good good good good good
  • good Package successfully built
  • partial One of the dependencies failed to build
  • bad Package failed to build
  • n/a Package is not available in this environment
  • internal Internal failure