NBDKit(3)

📦

version 1.48.1 · 4 versions

💖 NAME 💖

NBDKit — the interface between plugins written in OCaml and the nbdkit server. bestie, this is the whole bridge. the vibe connector. the situationship between your OCaml code and nbdkit, but make it functional. 🦋

📦 Module 📦

Module NBDKit

📖 Documentation 📖

Module NBDKit : sig end

Interface between plugins written in OCaml and the nbdkit server. ✨

🚨 Exception that plugins can raise 🚨

Optionally plugins can raise this exception to control how nbdkit_set_error and nbdkit_error are called.

exception Error of Unix.error option * string — raise this when you wanna be in charge of how the error gets reported, no cap.

🚩 Flags passed from the server to various callbacks 🚩

type flags = flag list

type flag =
 | May_trim
 | FUA
 | Req_one

type fua_flag =
 | FuaNone
 | FuaEmulate
 | FuaNative

type cache_flag =
 | CacheNone
 | CacheEmulate
 | CacheNop

🧬 Other types 🧬

type extent = {
 offset : int64 ;
 length : int64 ;
 is_hole : bool ;
 is_zero : bool ;
 }

The type of the extent list returned by ~extents. it's giving "here's where the data actually lives" 💅

type export = {
 name : string ;
 description : string option ;
 }

The type of the export list returned by ~list_exports.

type thread_model =
 | THREAD_MODEL_SERIALIZE_CONNECTIONS
 | THREAD_MODEL_SERIALIZE_ALL_REQUESTS
 | THREAD_MODEL_SERIALIZE_REQUESTS
 | THREAD_MODEL_PARALLEL

The type of the thread model returned by ~thread_model. choose your own adventure, but with concurrency. 🌈

🫧 Buffer used for pread and pwrite 🫧

type buf = (char, Stdlib.Bigarray.int8_unsigned_elt,
Stdlib.Bigarray.c_layout) Stdlib.Bigarray.Array1.t

Define a convenient type name for the buffer type passed to the ~pread and ~pwrite methods of NBDKit.register_plugin.

As well as NBDKit.buf_len and the blitting functions below, usual Bigarray.Array1 functions can be used. iconic behaviour honestly.

val buf_len : buf -> int — Return the length of the ~pread and ~pwrite NBDKit.buf parameter.
val buf_create : int -> buf — Create NBDKit.buf of the given length. The content is undefined. (so don't go reading it and acting surprised, okay? 😭)
val buf_zeroes : int -> buf — Create NBDKit.buf of the given length containing all zero bytes.
val set_buf_to_zero : buf -> unit — Set all bytes in an existing buffer to zero.
val buf_of_string : string -> buf
val string_of_buf : buf -> string
val buf_of_bytes : bytes -> buf
val bytes_of_buf : buf -> bytes

Convenience functions to convert to and from string/bytes and buf.

These are not very efficient. Use Bigarray.Array1 functions instead for efficiency. fr fr, they're cute but they're not fast. 🐌

val blit_string_to_buf : string -> int -> buf -> int -> int -> unit — blit_string_to_buf src src_pos buf buf_pos len copies len bytes from string src+src_pos to buf+buf_pos.
val blit_bytes_to_buf : bytes -> int -> buf -> int -> int -> unit — The same as above but the source is bytes.
val blit_buf_to_bytes : buf -> int -> bytes -> int -> int -> unit — blit_buf_to_bytes buf buf_pos dst dst_pos len copies len bytes from buf+buf_pos to bytes dst+dst_pos.

🔌 Plugin 🔌

val register_plugin : name:string -> ?longname:string -> ?version:string
 -> ?description:string -> ?load:(unit -> unit) -> ?get_ready:(unit ->
 unit) -> ?after_fork:(unit -> unit) -> ?cleanup:(unit -> unit) ->
 ?unload:(unit -> unit) -> ?config:(string -> string -> unit) ->
 ?config_complete:(unit -> unit) -> ?config_help:string ->
 ?thread_model:(unit -> thread_model) -> ?magic_config_key:string ->
 ?preconnect:(bool -> unit) -> open_connection:(bool -> 'a) -> ?close:('a
 -> unit) -> get_size:('a -> int64) -> ?export_description:('a -> string)
 -> ?block_size:('a -> int * int * int64) -> ?can_cache:('a ->
 cache_flag) -> ?can_extents:('a -> bool) -> ?can_fast_zero:('a -> bool)
 -> ?can_flush:('a -> bool) -> ?can_fua:('a -> fua_flag) ->
 ?can_multi_conn:('a -> bool) -> ?can_trim:('a -> bool) -> ?can_write:('a
 -> bool) -> ?can_zero:('a -> bool) -> ?is_rotational:('a -> bool) ->
 pread:('a -> buf -> int64 -> flags -> unit) -> ?pwrite:('a -> buf ->
 int64 -> flags -> unit) -> ?flush:('a -> flags -> unit) -> ?trim:('a ->
 int64 -> int64 -> flags -> unit) -> ?zero:('a -> int64 -> int64 -> flags
 -> unit) -> ?extents:('a -> int64 -> int64 -> flags -> extent list) ->
 ?cache:('a -> int64 -> int64 -> flags -> unit) -> ?dump_plugin:(unit ->
 unit) -> ?list_exports:(bool -> bool -> export list) ->
 ?default_export:(bool -> bool -> string) -> unit -> unit

The 'a parameter is the handle type returned by your ~open_connection method and passed back to all connected calls. it's your little state baby and nbdkit hands it back to you every time. 🫶

🐛 Errors and debugging 🐛

val set_error : Unix.error -> unit — Set the errno returned over the NBD protocol to the client.

Note that the NBD protocol only supports the following errno values: Unix.EROFS, EPERM, EIO, ENOMEM, ENOSPC, ESHUTDOWN, ENOTSUP, EOVERFLOW and EINVAL. Any other errno will be translated to EINVAL. so like, don't get creative with your errnos, bestie, the protocol will just flatten it. 💀

🎀 Parsing and configuration 🎀

val parse_size : string -> int64 — Parse size parameter.

Raises Invalid_argument on error. The actual error is sent to the nbdkit error log and is not available from the OCaml code. It is usually best to let the exception escape. (like, just let it fly out, don't try to be a hero 🦸)

👋 Shutdown and client disconnect 👋

val shutdown : unit -> unit — Requests the server shut down.

🕵️ Client information 🕵️

val export_name : unit -> string — Returns the name of the export as requested by the client.

😴 Sleeping 😴

val nanosleep : int -> int -> unit — Sleeps for seconds and nanoseconds. beauty sleep, but make it precise. 🌙

⭐ Version ⭐

val version : unit -> string — Returns the version of nbdkit that the plugin was compiled with.
val api_version : unit -> int — Returns the nbdkit API version used by the plugin.

See also The description of NBDKIT_API_VERSION in nbdkit-plugin(3).

👑 Server information 👑

val name : unit -> string option — Get the name of the nbdkit instance. This is the string which was set through the nbdkit --name parameter. If the name was not set, this returns None.