1nbdkit-ocaml-plugin(3)              NBDKIT              nbdkit-ocaml-plugin(3)
2
3
4

NAME

6       nbdkit-ocaml-plugin - writing nbdkit plugins in OCaml
7

SYNOPSIS

9        nbdkit /path/to/plugin.so [arguments...]
10
11        nbdkit plugin [arguments...]
12

DESCRIPTION

14       This manual page describes how to write nbdkit plugins in natively
15       compiled OCaml code.
16
17       Note this requires OCaml ≥ 4.02.2, which has support for shared
18       libraries.  See http://caml.inria.fr/mantis/view.php?id=6693
19

WRITING AN OCAML NBDKIT PLUGIN

21       For an example plugin written in OCaml, see:
22       https://github.com/libguestfs/nbdkit/blob/master/plugins/ocaml/example.ml
23
24       Broadly speaking, OCaml nbdkit plugins work like C ones, so you should
25       read nbdkit-plugin(3) first.
26
27       You should also look at "NBDKit.mli" which describes the plugin
28       interface for OCaml plugins.
29
30       Your OCaml code should call "NBDKit.register_plugin" like this:
31
32        let plugin = {
33          NBDKit.default_callbacks with
34            NBDKit.name     = "myplugin";
35            version         = "1.0";
36            open_connection = Some myplugin_open;
37            get_size        = Some myplugin_get_size;
38            pread           = Some myplugin_pread;
39            thread_model    = Some (fun () -> NBDKit.THREAD_MODEL_SERIALIZE_CONNECTIONS);
40            (* etc *)
41        }
42
43        let () = NBDKit.register_plugin plugin
44
45       Your plugin must call "register_plugin" exactly once when the plugin is
46       loaded.
47
48   Compiling an OCaml nbdkit plugin
49       OCaml nbdkit plugins are natively compiled into shared object ("*.so")
50       files which nbdkit loads like regular C plugins.
51
52       After writing your OCaml plugin ("myplugin.ml"), compile and link it
53       using this command:
54
55        ocamlopt.opt -output-obj -runtime-variant _pic \
56                     -o nbdkit-myplugin-plugin.so \
57                     NBDKit.cmx myplugin.ml \
58                     -cclib -lnbdkitocaml
59
60       You can then use "nbdkit-myplugin-plugin.so" as an nbdkit plugin (see
61       nbdkit(1), nbdkit-plugin(3)):
62
63        nbdkit ./nbdkit-myplugin-plugin.so [args ...]
64
65       or if the ".so" file is installed in the $plugindir directory:
66
67        nbdkit myplugin [args ...]
68
69   Handle
70       Your "open_connection" callback can return an OCaml value of any type.
71       The same value is passed back to the per-connection callbacks like
72       "get_size" and "pread".
73
74       Typically (although this is not a requirement) you define your own
75       handle struct in your plugin:
76
77        type handle = {
78          (* any per-connection data you want to store goes here *)
79          h_id : int; (* this is just an example field *)
80          h_readonly : bool;
81        }
82
83        let id = ref 0
84        let myplugin_open readonly =
85          (* return a newly allocated handle *)
86          incr id;
87          { h_id = !id; h_readonly = readonly }
88
89        let myplugin_get_size handle =
90          printf "handle ID = %d\n" handle.h_id;
91          (* ... *)
92
93   Errors
94       Plugins can return errors from methods by raising an exception.
95
96       If you need to control which errno is sent back to the client you have
97       to call "NBDKit.set_error" before raising the exception.
98
99       Note if you call some function in the OCaml "Unix" module or another
100       library which fails, then the errno of the failing system call will not
101       be returned to the client.  You have to catch the exception and call
102       "NBDKit.set_error" before re-raising the exception if you need to
103       control this.
104
105   Threads
106       One of the members in the plugin record passed to
107       "NBDKit.register_plugin" is "thread model", which must return one of
108       the values in the table below.  For more information on thread models,
109       see "THREADS" in nbdkit-plugin(3).  If this optional function is not
110       provided, the thread model defaults to THREAD_MODEL_PARALLEL.  Note
111       that because of the garbage collector lock in OCaml, callbacks are
112       never truly concurrent.
113
114       "NBDKit.THREAD_MODEL_SERIALIZE_CONNECTIONS"
115       "NBDKit.THREAD_MODEL_SERIALIZE_ALL_REQUESTS"
116       "NBDKit.THREAD_MODEL_SERIALIZE_REQUESTS"
117       "NBDKit.THREAD_MODEL_PARALLEL"
118
119   Debugging
120       You can add debugging messages which are printed only when nbdkit is in
121       verbose mode by calling:
122
123        NBDKit.debug fs [...]
124
125       This function works like "Printf.printf".
126

VERSION

128       OCaml plugins first appeared in nbdkit 1.2.
129

SEE ALSO

131       nbdkit(1), nbdkit-plugin(3), ocamlopt(1).
132

AUTHORS

134       Richard W.M. Jones
135
137       Copyright (C) 2014 Red Hat Inc.
138

LICENSE

140       Redistribution and use in source and binary forms, with or without
141       modification, are permitted provided that the following conditions are
142       met:
143
144       ·   Redistributions of source code must retain the above copyright
145           notice, this list of conditions and the following disclaimer.
146
147       ·   Redistributions in binary form must reproduce the above copyright
148           notice, this list of conditions and the following disclaimer in the
149           documentation and/or other materials provided with the
150           distribution.
151
152       ·   Neither the name of Red Hat nor the names of its contributors may
153           be used to endorse or promote products derived from this software
154           without specific prior written permission.
155
156       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
157       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
158       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
159       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
160       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
161       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
162       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
163       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
164       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
165       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
166       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
167
168
169
170nbdkit-1.16.1                     2019-12-03            nbdkit-ocaml-plugin(3)
Impressum