package cstruct

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

Install

Dune Dependency

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

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

Maintainers

  1. A
    anil@recoil.org

Sources

cstruct-3.2.1.tbz
sha256=0a9f481fd1cc94446b465371aceb0647d085ee7d12dde320d52a512e1520cb9e
md5=c1eb6a48f3d3b0b1e358f06a8c92a4c1

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: 14 Dec 2017

README

Cstruct -- access C-like structures directly from OCaml

v3.2.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-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.02.3 and later, since it provides a ppx extension point. The old camlp4 syntax extension is nolonger available; the last version which contained it was v1.9.0.

Local development

You can build the library via jbuilder, using make or jbuilder build directly. Since everything is built via jbuilder, you can also place this repository within a wider jbuilder 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
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

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.

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

Dependencies (3)

  1. sexplib
  2. jbuilder >= "1.0+beta10"
  3. ocaml >= "4.03.0"

Dev Dependencies (1)

  1. ounit with-test

  1. albatross < "1.3.0"
  2. angstrom >= "0.2.0" & < "0.7.0"
  3. arakoon >= "1.8.6" & < "1.8.12"
  4. arp < "3.0.0"
  5. arp-mirage
  6. asn1-combinators >= "0.1.2" & != "0.2.0-1" & < "0.2.6"
  7. awa < "0.0.4"
  8. awa-lwt < "0.0.4"
  9. awa-mirage < "0.0.4"
  10. balancer
  11. bip32
  12. buffer-pool
  13. capnp-rpc-net >= "1.1" & < "1.2.1"
  14. certify >= "0.2"
  15. chacha < "1.1.0"
  16. channel
  17. charrua < "1.4.1"
  18. charrua-client < "1.4.1"
  19. charrua-client-lwt
  20. charrua-client-mirage < "0.12.0"
  21. charrua-core >= "0.8"
  22. charrua-server < "1.4.1"
  23. charrua-unix = "0.6"
  24. cohttp >= "0.9.7" & < "0.10.0"
  25. conduit >= "0.6.0" & < "0.15.2"
  26. conduit-async = "3.0.0"
  27. conduit-lwt = "3.0.0"
  28. conduit-mirage != "3.0.0"
  29. conex < "0.10.0"
  30. conex-mirage-crypto
  31. conex-nocrypto
  32. cowabloga >= "0.0.5"
  33. crc
  34. crunch >= "2.0.0" & < "3.0.0"
  35. cstruct-async >= "3.2.0" & != "3.4.0" & < "4.0.0"
  36. cstruct-lwt >= "3.1.0" & != "3.4.0" & < "4.0.0"
  37. cstruct-unix >= "3.1.0" & != "3.4.0" & < "4.0.0"
  38. datakit
  39. datakit-ci >= "0.10.0" & < "0.12.4"
  40. datakit-client
  41. datakit-client-9p
  42. datakit-server
  43. depyt
  44. dns >= "0.20.0" & < "6.0.0"
  45. dns-forward >= "0.9.0"
  46. dnssd
  47. dream < "1.0.0~alpha2"
  48. duff < "0.3"
  49. eqaf >= "0.8" & < "0.10"
  50. eqaf-cstruct
  51. ethernet < "2.2.1"
  52. fat-filesystem >= "0.11.0" & < "0.15.1"
  53. frenetic < "2.0.0" | >= "3.2.0" & < "5.0.0"
  54. git >= "2.0.0" & < "3.0.0"
  55. git-http < "1.11.0"
  56. github-hooks >= "0.2.0"
  57. gluten-mirage < "0.3.0"
  58. gpt
  59. h2-mirage
  60. hacl-star >= "0.7.0"
  61. hex >= "0.2.0"
  62. hkdf < "2.0.0"
  63. httpun-mirage
  64. httpun-ws-mirage
  65. hvsock < "3.0.0"
  66. io-page
  67. io-page-unix
  68. io-page-xen
  69. ipaddr-cstruct < "5.2.0"
  70. ipv6-multicast >= "0.9"
  71. irmin >= "0.9.0" & < "2.0.0"
  72. irmin-git >= "2.3.0"
  73. irmin-indexeddb >= "0.3"
  74. key-parsers >= "0.5.0" & < "1.2.1"
  75. launchd
  76. letsencrypt = "0.2.5"
  77. letsencrypt-app < "0.4.0"
  78. macaddr-cstruct < "5.2.0"
  79. metrics-mirage
  80. mirage >= "0.7.2" & < "0.9.0" | >= "0.10.0" & < "2.4.0"
  81. mirage-block < "1.0.0"
  82. mirage-block-ccm < "1.1.0"
  83. mirage-block-combinators < "3.0.0"
  84. mirage-block-lwt
  85. mirage-block-ramdisk
  86. mirage-block-solo5 < "0.6.2"
  87. mirage-block-unix >= "2.0.0" & < "2.13.0"
  88. mirage-block-xen >= "1.4.0" & < "2.1.1"
  89. mirage-btrees
  90. mirage-channel-lwt
  91. mirage-clock-unix < "1.0.0"
  92. mirage-clock-xen < "1.0.0"
  93. mirage-conduit < "2.0.0" | >= "2.3.1"
  94. mirage-console-lwt
  95. mirage-console-solo5 >= "0.2.0"
  96. mirage-console-unix >= "2.2.1" & < "3.0.0"
  97. mirage-console-xen = "4.0.0"
  98. mirage-console-xen-backend >= "2.3.2" & < "2.3.4" | = "4.0.0"
  99. mirage-crypto < "0.10.4"
  100. mirage-crypto-pk < "0.10.4"
  101. mirage-crypto-rng < "0.7.0"
  102. mirage-dns != "2.6.0" & < "2.7.0"
  103. mirage-entropy < "0.5.0"
  104. mirage-entropy-xen < "0.3.0"
  105. mirage-flow < "1.2.0"
  106. mirage-flow-lwt
  107. mirage-flow-rawlink
  108. mirage-flow-unix < "2.0.0"
  109. mirage-fs >= "0.4.0" & < "1.0.0"
  110. mirage-fs-lwt
  111. mirage-fs-mem
  112. mirage-fs-unix
  113. mirage-kv-lwt
  114. mirage-kv-unix
  115. mirage-nat < "2.2.4"
  116. mirage-net = "0.5.2"
  117. mirage-net-fd
  118. mirage-net-lwt
  119. mirage-net-macosx
  120. mirage-net-solo5
  121. mirage-net-unix < "2.1.0" | >= "2.2.1"
  122. mirage-net-xen != "1.4.2" & < "2.1.0"
  123. mirage-profile >= "0.8.2"
  124. mirage-protocols-lwt
  125. mirage-qubes != "0.2" & < "0.9.2"
  126. mirage-qubes-ipv4 < "0.9.3"
  127. mirage-random < "2.0.0"
  128. mirage-random-stdlib
  129. mirage-random-test
  130. mirage-solo5
  131. mirage-stack-lwt
  132. mirage-tc
  133. mirage-tcpip-unix
  134. mirage-tcpip-xen
  135. mirage-types-lwt < "3.7.1"
  136. mirage-unix < "0.9.4" | >= "2.5.0" & < "3.0.8"
  137. mirage-vnetif < "0.6.0"
  138. mirage-www < "0.4.0" | >= "1.1.0"
  139. mirage-xen < "2.0.0" | >= "2.6.0"
  140. monorobot
  141. mrt-format
  142. mstruct
  143. nbd >= "3.0.0" & < "6.0.0"
  144. netchannel < "2.1.0"
  145. nocrypto < "0.4.0" | >= "0.5.4"
  146. noise
  147. openflow < "0.2.0"
  148. otr >= "0.3.1" & < "0.3.9"
  149. ox < "1.1.1"
  150. pbkdf < "0.3.0" | = "1.1.0"
  151. pcap-format >= "0.4.0"
  152. ppx_cstruct = "3.2.1"
  153. protocol-9p < "0.5.1" | >= "0.10.0" & < "2.0.1"
  154. protocol-9p-tool = "0.12.0" | >= "2.0.0" & < "2.0.2"
  155. protocol-9p-unix < "2.0.2"
  156. qcow < "0.11.0"
  157. qcow-format >= "0.4.1"
  158. qcow-tool
  159. randomconv < "0.2.0"
  160. rawlink >= "0.6" & < "1.2"
  161. resp-mirage = "0.10.0"
  162. rfc6287 >= "1.0.2"
  163. salsa20 < "1.2.0"
  164. salsa20-core >= "0.3.0" & < "1.1.0"
  165. scrypt-kdf >= "0.2.0" & < "1.2.0"
  166. secp256k1-internal < "0.3.0"
  167. sendmail >= "0.4.1" & < "0.5.0"
  168. shared-block-ring < "3.0.1"
  169. shared-memory-ring >= "1.2.0" & < "3.1.1"
  170. shared-memory-ring-lwt
  171. slack
  172. ssh-agent
  173. tar < "2.0.0"
  174. tar-mirage
  175. tar-unix < "2.0.0"
  176. tcpip < "2.3.0" | >= "2.7.0" & < "6.3.0"
  177. tezos-lmdb
  178. tls >= "0.9.0" & < "0.10.2"
  179. u2f = "0.1.1"
  180. uecc
  181. vchan >= "2.1.0" & < "6.0.1"
  182. vchan-unix
  183. vchan-xen
  184. vhd-format >= "0.8.0"
  185. vhd-format-lwt
  186. vhd-tool < "0.12.0"
  187. vmnet >= "1.1.0"
  188. x509 < "0.6.3"
  189. xe
  190. xen-api-client >= "0.9.6" & < "0.9.14"
  191. xen-block-driver >= "0.2.5"
  192. xen-gnt
  193. xenstore >= "1.3.0" & < "2.3.0"

Conflicts

None

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct