NBDKit - Man Page

Module   NBDKit

Module NBDKit
: sig end

Interface between plugins written in OCaml and the nbdkit server.

Read nbdkit-ocaml-plugin(3) first.

type flags = flag list

Flags passed from the server to various callbacks.

type flag =
| May_trim
| FUA
| Req_one

type fua_flag =
| FuaNone
| FuaEmulate
| FuaNative

type cache_flag =
| CacheNone
| CacheEmulate
| CacheNop

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

The type of the extent list returned by NBDKit.plugin.extents

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

The type of the export list returned by NBDKit.plugin.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 NBDKit.plugin.thread_model

type 'a plugin = {
name : string ;  (* required field
*)
longname : string ;
version : string ;
description : string ;
load : (unit -> unit) option ;
get_ready : (unit -> unit) option ;
after_fork : (unit -> unit) option ;
cleanup : (unit -> unit) option ;
unload : (unit -> unit) option ;
config : (string -> string -> unit) option ;
config_complete : (unit -> unit) option ;
config_help : string ;
thread_model : (unit -> thread_model) option ;
preconnect : (bool -> unit) option ;
open_connection : (bool -> 'a) option ;  (* required field
*)
close : ('a -> unit) option ;
get_size : ('a -> int64) option ;  (* required field
*)
can_cache : ('a -> cache_flag) option ;
can_extents : ('a -> bool) option ;
can_fast_zero : ('a -> bool) option ;
can_flush : ('a -> bool) option ;
can_fua : ('a -> fua_flag) option ;
can_multi_conn : ('a -> bool) option ;
can_trim : ('a -> bool) option ;
can_write : ('a -> bool) option ;
can_zero : ('a -> bool) option ;
is_rotational : ('a -> bool) option ;
pread : ('a -> int32 -> int64 -> flags -> string) option ;  (* required field
*)
pwrite : ('a -> string -> int64 -> flags -> unit) option ;
flush : ('a -> flags -> unit) option ;
trim : ('a -> int32 -> int64 -> flags -> unit) option ;
zero : ('a -> int32 -> int64 -> flags -> unit) option ;
extents : ('a -> int32 -> int64 -> flags -> extent list) option ;
cache : ('a -> int32 -> int64 -> flags -> unit) option ;
dump_plugin : (unit -> unit) option ;
list_exports : (bool -> bool -> export list) option ;
default_export : (bool -> bool -> string) option ;
export_description : ('a -> string) option ;
}

The plugin fields and callbacks.

The 'a parameter is the handle type returned by your open_connection method and passed back to all connected calls.

val default_callbacks : 'a plugin

The plugin with all fields set to None , so you can write { default_callbacks with field1 = Some foo1; field2 = Some foo2 }

val register_plugin : 'a plugin -> unit

Register the plugin with nbdkit.

val set_error : Unix.error -> unit

Set the errno returned over the NBD protocol to the client.

Notice however that the NBD protocol only supports a small handful of errno values.  Any other errno will be translated into EINVAL .

val parse_size : string -> int64

Bindings for nbdkit_parse_size , nbdkit_parse_bool and nbdkit_read_password .  See nbdkit-plugin(3) for information about these functions.

On error these functions all raise Invalid_argument .  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.

val parse_bool : string -> bool

val read_password : string -> string

val realpath : string -> string

Binding for nbdkit_realpath . Returns the canonical path from a path parameter.

val nanosleep : int -> int -> unit

Binding for nbdkit_nanosleep .  Sleeps for seconds and nanoseconds.

val export_name : unit -> string

Binding for nbdkit_export_name .  Returns the name of the export as requested by the client.

val shutdown : unit -> unit

Binding for nbdkit_shutdown .  Requests the server shut down.

val debug : ('a, unit, string, unit) Stdlib.format4 -> 'a

Print a debug message when nbdkit is in verbose mode.

val version : unit -> string

Return the version of nbdkit that the plugin was compiled with.

val peer_pid : unit -> int64

Binding for nbdkit_peer_pid .

val peer_uid : unit -> int64

Binding for nbdkit_peer_uid .

val peer_gid : unit -> int64

Binding for nbdkit_peer_gid .

nbdkit-ocaml-plugin(3), nbdkit-release-notes-1.24(1).