libnbd-ocaml(3)

💅 libnbd-ocaml 💅

okay bestie, so this is the manual page for libnbd-ocaml — it's literally the whole "how do I use libnbd from OCaml" situation, and honestly? it ate. the manual name is right there in the title, no cap. ✨

---

🌸 SYNOPSIS 🌸

classic vibe, explicit close and everything:

let nbd = NBD.create () in
NBD.connect_uri nbd "nbd://localhost";
let size = NBD.get_size nbd in
printf "%Ld\n" size;
NBD.close ()

alt syntax, aka the responsible one — this bad boy makes sure close gets called even if an exception gets thrown mid-character-development:

let size =
  NBD.with_handle (
    fun nbd ->
      NBD.connect_uri nbd "nbd://localhost";
      NBD.get_size nbd
  ) in
printf "%Ld\n" size

to compile it, run this:

ocamlopt -I +nbd mlnbd.cmxa prog.ml -o prog

or, if you're a findlib girlie:

ocamlfind opt -package nbd -linkpkg prog.ml -o prog

---

🦋 DESCRIPTION 🦋

so this page is all about how to use libnbd to talk to Network Block Device (NBD) servers from the OCaml programming language. 🎀

the OCaml bindings work very similarly to the C bindings, so you should start by reading libnbd(3) — yes, go read it, it's giving required reading, iykyk.

for the OCaml API documentation, that's NBD(3). go be obsessed with it. 💜

---

👑 HANDLES 👑

make a libnbd handle of type NBD.t by calling NBD.create (). that's it, that's the whole thing. slay.

you can either close the handle explicitly by calling NBD.close, or it gets closed automatically when it's garbage collected. convenient! but listen — if you call any other method on a handle that you've already explicitly closed, the API will throw an NBD.Closed exception. so like, don't do that. 🫶

NBD.with_handle is the icon that makes sure the handle gets closed in a timely manner. see the example up in the SYNOPSIS above. periodt.

---

😭 ERRORS 😭

libnbd errors get turned automatically into exceptions of this type:

NBD.Error (str, Unix.error option)

the first exception parameter is a string — it's the printable error message. the second is the OCaml Unix.error code, if available (see nbd_get_errno(3)). so like, sometimes you get the code, sometimes you don't, it's fine, we cope. 💀

✨ Callbacks with int ref error parameter ✨

some callbacks take an error parameter of type int ref, which corresponds to the int *error that gets passed to those callbacks in C. see also: Callbacks with "int *error" parameter in libnbd(3). 🔥

if an error happens during the callback, you can update the int inside the reference — set it to a C-compatible errno. and to convert an OCaml Unix.error into a C-compatible errno, call NBD.errno_of_unix_error. literally so handy. 💅

---

🌈 EXAMPLES 🌈

this directory contains examples written in OCaml, if you need inspo:

https://gitlab.com/nbdkit/libnbd/tree/master/ocaml/examples

---

⭐ SEE ALSO ⭐

libnbd(3), NBD(3).

---

🧚 AUTHORS 🧚

Richard W.M. Jones

---

🍓 COPYRIGHT 🍓

Copyright Red Hat

---

💖 LICENSE 💖

bestie this part is legally iconic so we keep it in its original form, no edits:

this library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

this library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. see the GNU Lesser General Public License for more details.

you should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

---

🎀 and that's the page!! mwah 💋 — this was libnbd-1.24.4, dated 2026-10-13, and it remains libnbd-ocaml(3) to its very last breath. go close your handles, bestie. 🫶✨