package cstruct

  1. Overview
  2. Docs
Access C-like structures directly from OCaml

Install

Dune Dependency

Authors

Maintainers

Sources

cstruct-v6.0.1.tbz
sha256=4a67bb8f042753453c59eabf0e47865631253ba694091ce6062aac05d47a9bed
sha512=3eeeb6ae0fd3b625cf1d308498f0a1e6951d16566561f3362fdf74e7158d92d8f6c6d9fa968ff15f8c19a1886dce99d0ef17b44dbb37b97cc68c9b088fdc2248

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

Published: 28 Jul 2021

README

Cstruct -- access C-like structures directly from OCaml

v6.0.1

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

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. bigarray-compat
  2. dune >= "2.0.0"
  3. ocaml >= "4.03.0"

Dev Dependencies (3)

  1. ocaml with-test & < "4.08"
  2. crowbar with-test
  3. alcotest with-test

  1. albatross < "2.3.0"
  2. angstrom < "0.7.0"
  3. arp
  4. asn1-combinators >= "0.2.5" & < "0.3.1"
  5. async_unix >= "v0.17.0"
  6. awa
  7. awa-mirage
  8. balancer
  9. bip32
  10. buffer-pool
  11. builder < "0.4.0"
  12. builder-web < "0.2.0"
  13. capnp-rpc-net
  14. carton < "0.7.2"
  15. carton-git < "0.7.2"
  16. carton-lwt < "0.7.2"
  17. certify
  18. chacha
  19. chamelon
  20. charrua
  21. charrua-client
  22. charrua-server
  23. cohttp-mirage
  24. colombe < "0.2.0"
  25. conduit-mirage
  26. conex < "0.10.0"
  27. conex-mirage-crypto
  28. cowabloga
  29. crc
  30. cstruct-lwt = "3.7.0" | = "6.0.1"
  31. cstruct-sexp = "6.0.1"
  32. cstruct-unix < "6.2.0"
  33. current-albatross-deployer
  34. current_git
  35. current_github
  36. current_web
  37. datakit-server
  38. depyt
  39. dirsp-proscript
  40. dns >= "4.4.1" & < "9.1.0"
  41. dns-cli < "9.1.0"
  42. dns-client < "7.0.3"
  43. dns-forward
  44. dns-mirage
  45. dns-server
  46. dns-stub
  47. dns-tsig < "9.1.0"
  48. dnssd
  49. dnssec < "9.1.0"
  50. dream
  51. duff < "0.3"
  52. eio
  53. eqaf >= "0.8" & < "0.10"
  54. eqaf-cstruct
  55. ethernet
  56. fat-filesystem >= "0.13.0"
  57. fiat-p256
  58. frenetic
  59. geojsone >= "0.2.0"
  60. git
  61. git-cohttp
  62. git-cohttp-unix
  63. git-kv >= "0.2.0"
  64. git-mirage
  65. git-unix >= "3.2.0"
  66. github-hooks
  67. gluten-mirage < "0.5.2"
  68. gpt
  69. h2-mirage
  70. hacl-star >= "0.7.0"
  71. hacl_x25519
  72. hex >= "1.4.0"
  73. hkdf
  74. http-multipart-formdata >= "3.0.0"
  75. httpun-mirage
  76. httpun-ws-mirage
  77. hvsock
  78. io-page
  79. io-page-unix
  80. ipaddr-cstruct
  81. ipv6-multicast
  82. irmin-git
  83. irmin-indexeddb
  84. jose < "0.10.0"
  85. key-parsers >= "1.0.0"
  86. launchd
  87. learn-ocaml-client
  88. ledgerwallet
  89. letsencrypt < "1.0.0"
  90. letsencrypt-app < "1.0.0"
  91. lt-code
  92. macaddr-cstruct
  93. memtrace_viewer < "v0.15.0"
  94. mimic
  95. mirage-block >= "2.0.1"
  96. mirage-block-ccm
  97. mirage-block-combinators >= "3.0.2"
  98. mirage-block-ramdisk
  99. mirage-block-solo5
  100. mirage-block-unikraft
  101. mirage-block-unix
  102. mirage-block-xen
  103. mirage-btrees
  104. mirage-channel >= "4.0.1"
  105. mirage-channel-lwt
  106. mirage-conduit
  107. mirage-console-lwt
  108. mirage-crypto < "1.1.0"
  109. mirage-crypto-ec < "1.1.0"
  110. mirage-crypto-pk < "1.1.0"
  111. mirage-crypto-rng < "1.1.0"
  112. mirage-crypto-rng-eio < "1.2.0"
  113. mirage-crypto-rng-mirage < "1.1.0"
  114. mirage-flow >= "3.0.0"
  115. mirage-flow-combinators
  116. mirage-flow-lwt
  117. mirage-flow-unix
  118. mirage-fs >= "4.0.0"
  119. mirage-fs-lwt
  120. mirage-kv-lwt
  121. mirage-kv-unix
  122. mirage-nat
  123. mirage-net >= "4.0.0"
  124. mirage-net-lwt
  125. mirage-net-macosx
  126. mirage-net-solo5
  127. mirage-net-unikraft
  128. mirage-net-unix
  129. mirage-net-xen
  130. mirage-profile
  131. mirage-protocols >= "7.0.0"
  132. mirage-protocols-lwt
  133. mirage-qubes
  134. mirage-random
  135. mirage-solo5 < "0.10.0"
  136. mirage-stack-lwt
  137. mirage-tc
  138. mirage-types-lwt
  139. mirage-vnetif
  140. mirage-xen
  141. monorobot
  142. mstruct
  143. nbd >= "4.0.3"
  144. nocrypto
  145. noise
  146. oneffs
  147. otr < "1.0.0"
  148. paf
  149. pbkdf
  150. pcap-format >= "0.5.2"
  151. pf-qubes
  152. plebeia < "2.0.0"
  153. ppx_cstruct = "6.0.1"
  154. protocol-9p >= "2.0.2"
  155. protocol-9p-tool = "0.12.0" | >= "2.0.0"
  156. protocol-9p-unix = "0.11.3" | >= "2.0.2"
  157. qcow >= "0.11.0"
  158. qcow-tool
  159. randomconv < "0.2.0"
  160. rawlink < "1.2"
  161. reparse >= "3.0.0"
  162. reparse-lwt
  163. reparse-lwt-unix
  164. resp-mirage = "0.10.0"
  165. rfc6287
  166. salsa20
  167. salsa20-core >= "1.0.0" & < "2.0.0"
  168. scrypt-kdf
  169. secp256k1-internal
  170. sendmail >= "0.4.1"
  171. shared-block-ring
  172. shared-memory-ring
  173. shared-memory-ring-lwt
  174. sihl >= "3.0.0"
  175. slack
  176. solo5-elftool < "0.4.0"
  177. ssh-agent
  178. swapfs
  179. tar < "3.3.0"
  180. tar-mirage
  181. tar-unix < "3.3.0"
  182. tcpip < "9.0.1"
  183. tls >= "0.12.8" & < "1.0.4"
  184. tls-liquidsoap
  185. uecc
  186. uring
  187. vchan
  188. vchan-unix
  189. vchan-xen
  190. vhd-format >= "0.12.0"
  191. vhd-format-lwt >= "0.12.1"
  192. vmnet
  193. wayland
  194. webauthn < "0.2.0"
  195. x509 < "1.0.6"
  196. xen-gnt

Conflicts (1)

  1. js_of_ocaml < "3.5.0"
OCaml

Innovation. Community. Security.