package cstruct

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

Install

Dune Dependency

Authors

Maintainers

Sources

cstruct-v6.0.0.tbz
sha256=78a16d2f258cf308e9600374d8fe4ec21cf09e618acf86337663805f90642676
sha512=9f8be171ec365f04df18cb4c144c9cfb843f6a3190d01006138a7736b80b3012788b9b799d784b9a2bea480f92d635edd138ee8ac619442ca2fb666279d7c2d1

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: 24 Sep 2020

README

Cstruct -- access C-like structures directly from OCaml

v6.0.0

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 (1)

  1. alcotest with-test

  1. albatross
  2. angstrom >= "0.2.0" & < "0.7.0"
  3. arakoon >= "1.8.6" & < "1.8.12"
  4. arp >= "0.2.1"
  5. arp-mirage
  6. asn1-combinators >= "0.2.3" & < "0.3.0"
  7. awa
  8. awa-lwt
  9. awa-mirage
  10. balancer
  11. bip32
  12. buffer-pool
  13. builder
  14. builder-web
  15. capnp-rpc-net >= "1.1"
  16. carton < "0.4.4"
  17. carton-git < "0.4.4"
  18. carton-lwt < "0.4.4"
  19. certify >= "0.2"
  20. chacha
  21. chamelon
  22. channel
  23. charrua
  24. charrua-client
  25. charrua-client-lwt
  26. charrua-client-mirage < "0.12.0"
  27. charrua-server
  28. charrua-unix = "0.6"
  29. cohttp >= "0.9.7" & < "0.10.0"
  30. cohttp-mirage >= "6.0.0~alpha0"
  31. colombe < "0.2.0"
  32. conduit >= "0.6.0" & < "0.15.2"
  33. conduit-async = "3.0.0"
  34. conduit-lwt = "3.0.0"
  35. conduit-mirage != "3.0.0"
  36. conex < "0.10.0"
  37. conex-mirage-crypto
  38. conex-nocrypto >= "0.11.0"
  39. cowabloga >= "0.0.5"
  40. crc
  41. crunch >= "2.0.0" & < "3.0.0"
  42. cstruct-async >= "3.4.0" & < "4.0.0" | = "6.0.0"
  43. cstruct-lwt >= "3.4.0" & < "4.0.0" | = "6.0.0"
  44. cstruct-sexp = "5.0.0" | = "6.0.0"
  45. cstruct-unix >= "3.1.0" & < "3.2.0" | >= "3.4.0" & < "4.0.0" | = "6.0.0"
  46. current_git >= "0.5"
  47. current_github >= "0.4"
  48. current_web >= "0.4"
  49. datakit
  50. datakit-ci >= "0.12.4"
  51. datakit-client
  52. datakit-client-9p
  53. datakit-server
  54. depyt >= "0.2.0"
  55. dirsp-proscript
  56. dns >= "4.0.0"
  57. dns-cli >= "6.0.0"
  58. dns-client < "7.0.0"
  59. dns-forward >= "0.9.0"
  60. dns-mirage >= "6.0.0"
  61. dns-server >= "6.0.0"
  62. dns-stub >= "6.0.0"
  63. dns-tsig >= "6.0.0"
  64. dnssd
  65. dnssec
  66. dream
  67. duff < "0.3"
  68. eqaf >= "0.8"
  69. ethernet
  70. fat-filesystem >= "0.13.0"
  71. fiat-p256
  72. frenetic < "2.0.0" | >= "3.2.0" & < "5.0.0"
  73. git >= "2.0.0"
  74. git-cohttp
  75. git-cohttp-mirage
  76. git-cohttp-unix
  77. git-mirage >= "3.0.0"
  78. git-unix >= "3.0.0"
  79. github-hooks >= "0.2.0"
  80. gluten-mirage
  81. gpt
  82. h2-mirage
  83. hacl-star >= "0.7.0"
  84. hacl_x25519
  85. hex >= "1.4.0"
  86. hkdf
  87. http-multipart-formdata >= "3.0.0"
  88. hvsock
  89. io-page
  90. io-page-unix
  91. io-page-xen
  92. ipaddr-cstruct
  93. ipv6-multicast >= "0.9"
  94. irmin >= "0.9.0" & < "1.0.0" | >= "1.1.0" & < "2.0.0"
  95. irmin-git >= "2.3.0"
  96. irmin-indexeddb >= "0.3"
  97. jose
  98. key-parsers >= "0.5.0" & < "0.9.2" | >= "1.0.0"
  99. launchd
  100. learn-ocaml-client
  101. ledgerwallet
  102. letsencrypt = "0.2.5" | >= "0.4.0"
  103. letsencrypt-app
  104. lt-code
  105. macaddr-cstruct
  106. mbr-format = "1.0.0"
  107. memtrace_viewer < "v0.15.0"
  108. metrics-mirage
  109. mimic
  110. mirage >= "0.7.2" & < "0.9.0" | >= "0.10.0" & < "2.4.0"
  111. mirage-block >= "2.0.0"
  112. mirage-block-ccm
  113. mirage-block-combinators
  114. mirage-block-lwt
  115. mirage-block-ramdisk
  116. mirage-block-solo5
  117. mirage-block-unix = "2.0.0" | = "2.7.0" | >= "2.11.1"
  118. mirage-block-xen >= "1.4.0" & < "1.5.2" | >= "1.6.0"
  119. mirage-btrees
  120. mirage-channel >= "4.0.0"
  121. mirage-channel-lwt
  122. mirage-clock-unix < "1.0.0"
  123. mirage-clock-xen < "1.0.0"
  124. mirage-conduit < "2.0.0" | >= "2.3.1"
  125. mirage-console >= "3.0.0" & < "4.0.0"
  126. mirage-console-lwt
  127. mirage-console-solo5 >= "0.2.0"
  128. mirage-console-unix >= "2.2.1"
  129. mirage-console-xen >= "4.0.0"
  130. mirage-console-xen-backend >= "2.3.2" & < "2.3.4" | >= "4.0.0"
  131. mirage-crypto
  132. mirage-crypto-ec
  133. mirage-crypto-entropy
  134. mirage-crypto-pk
  135. mirage-crypto-rng
  136. mirage-crypto-rng-eio
  137. mirage-crypto-rng-mirage
  138. mirage-dns != "2.6.0" & < "2.7.0"
  139. mirage-entropy
  140. mirage-entropy-xen < "0.3.0"
  141. mirage-flow < "1.2.0" | >= "2.0.0"
  142. mirage-flow-combinators
  143. mirage-flow-lwt
  144. mirage-flow-rawlink
  145. mirage-flow-unix
  146. mirage-fs >= "0.4.0" & < "1.0.0" | >= "3.0.0"
  147. mirage-fs-lwt
  148. mirage-fs-mem
  149. mirage-fs-unix < "1.1.0" | >= "1.4.0" & != "1.5.0"
  150. mirage-kv-lwt
  151. mirage-kv-unix
  152. mirage-nat
  153. mirage-net = "0.5.2" | >= "3.0.0"
  154. mirage-net-fd < "0.2.1"
  155. mirage-net-lwt
  156. mirage-net-macosx
  157. mirage-net-solo5
  158. mirage-net-unix < "2.1.0" | >= "2.2.1" & < "2.4.1" | >= "2.6.0"
  159. mirage-net-xen != "1.4.2" & != "1.7.0"
  160. mirage-profile >= "0.8.2"
  161. mirage-protocols >= "6.0.0" & < "8.0.0"
  162. mirage-protocols-lwt
  163. mirage-qubes != "0.2" & < "0.5" | >= "0.7.0"
  164. mirage-qubes-ipv4 < "0.9.4"
  165. mirage-random < "4.0.0"
  166. mirage-random-stdlib
  167. mirage-random-test
  168. mirage-solo5
  169. mirage-stack-lwt
  170. mirage-tc
  171. mirage-tcpip-unix
  172. mirage-tcpip-xen
  173. mirage-types-lwt < "3.7.1"
  174. mirage-unix < "0.9.4" | >= "2.5.0" & < "3.0.8"
  175. mirage-vnetif
  176. mirage-vnetif-stack
  177. mirage-www < "0.4.0" | >= "1.1.0"
  178. mirage-xen < "2.0.0" | >= "2.6.0"
  179. monorobot
  180. mrt-format >= "0.3.1"
  181. mstruct
  182. nbd >= "4.0.3"
  183. netchannel
  184. nocrypto < "0.4.0" | >= "0.5.4-1"
  185. noise
  186. oneffs
  187. openflow < "0.2.0"
  188. otr = "0.3.1" | >= "0.3.5"
  189. ox < "1.1.1"
  190. paf >= "0.0.5"
  191. pbkdf < "0.3.0" | >= "1.1.0"
  192. pcap-format >= "0.5.2"
  193. pf-qubes
  194. plebeia < "2.0.0"
  195. ppx_cstruct = "6.0.0"
  196. protocol-9p >= "2.0.2"
  197. protocol-9p-tool = "0.12.0" | >= "2.0.0"
  198. protocol-9p-unix = "0.11.3" | >= "2.0.2"
  199. qcow >= "0.11.0"
  200. qcow-tool
  201. randomconv < "0.2.0"
  202. rawlink >= "0.6" & < "1.2"
  203. reparse >= "3.0.0"
  204. reparse-lwt
  205. reparse-lwt-unix
  206. resp-mirage = "0.10.0"
  207. rfc6287 >= "1.0.2"
  208. salsa20
  209. salsa20-core >= "0.3.0"
  210. scrypt-kdf >= "0.2.0"
  211. secp256k1-internal
  212. sendmail >= "0.4.1"
  213. shared-block-ring
  214. shared-memory-ring >= "3.0.1"
  215. shared-memory-ring-lwt
  216. slack
  217. solo5-elftool
  218. ssh-agent
  219. tar >= "1.0.0"
  220. tar-mirage
  221. tar-unix != "1.0.0"
  222. tcpip >= "3.3.0"
  223. tezos-lmdb
  224. tls >= "0.12.5"
  225. u2f >= "0.1.1"
  226. uecc
  227. uring < "0.2"
  228. vchan >= "3.0.0"
  229. vchan-unix
  230. vchan-xen
  231. vhd-format >= "0.12.0"
  232. vhd-format-lwt >= "0.12.1"
  233. vhd-tool < "0.12.0"
  234. vmnet >= "1.1.0"
  235. wayland
  236. webauthn
  237. x509 >= "0.6.3"
  238. xe
  239. xen-api-client >= "0.9.6" & < "0.9.14"
  240. xen-block-driver >= "0.2.5"
  241. xen-gnt
  242. xenstore >= "2.1.0" & < "2.3.0"

Conflicts (1)

  1. js_of_ocaml < "3.5.0"
OCaml

Innovation. Community. Security.