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

NAME

6       nbdkit-perl-plugin - nbdkit perl plugin
7

SYNOPSIS

9        nbdkit perl /path/to/plugin.pl [arguments...]
10

DESCRIPTION

12       "nbdkit-perl-plugin" is an embedded Perl interpreter for nbdkit(1),
13       allowing you to write nbdkit plugins in Perl.
14
15   If you have been given an nbdkit Perl plugin
16       Assuming you have a Perl script which is an nbdkit plugin, you run it
17       like this:
18
19        nbdkit perl /path/to/plugin.pl
20
21       You may have to add further "key=value" arguments to the command line.
22       Read the Perl script to see if it requires any.
23

WRITING A PERL NBDKIT PLUGIN

25       For an example plugin written in Perl, see:
26       https://github.com/libguestfs/nbdkit/blob/master/plugins/perl/example.pl
27
28       Broadly speaking, Perl nbdkit plugins work like C ones, so you should
29       read nbdkit-plugin(3) first.
30
31       To write a Perl nbdkit plugin, you create a Perl file which contains at
32       least the following required subroutines:
33
34        sub open
35        {
36          # see below
37        }
38        sub get_size
39        {
40          # see below
41        }
42        sub pread
43        {
44          # see below
45        }
46
47       Note that the subroutines must have those literal names (like "open"),
48       because the C part looks up and calls those functions directly.  You
49       may want to include documentation and globals (eg. for storing global
50       state).  Also any top-level statements, "BEGIN" statements, "END"
51       statements and so on are run when nbdkit starts up and shuts down, just
52       like ordinary Perl.
53
54   Executable script
55       If you want you can make the script executable and include a "shebang"
56       at the top:
57
58        #!/usr/sbin/nbdkit perl
59
60       See also "Shebang scripts" in nbdkit(1).
61
62       These scripts can also be installed in the $plugindir.  See "WRITING
63       PLUGINS IN OTHER PROGRAMMING LANGUAGES" in nbdkit-plugin(3).
64
65   Methods
66       Your script has access to the following methods in the "Nbdkit" package
67       (in fact, attempting to "use Nbdkit" will fail, the methods are already
68       available):
69
70        Nbdkit::set_error($err);
71
72       Record $err as the reason you are about to throw an exception. $err
73       should correspond to usual errno values, where it may help to "use
74       POSIX()".
75
76   Exceptions
77       Instead of returning error codes as in C, Perl callbacks should
78       indicate problems by throwing Perl exceptions (ie. "die", "croak" etc).
79       The Perl error message is captured and printed by nbdkit.  Remember to
80       use "Nbdkit::set_error" if you need to control which error is sent back
81       to the client; if omitted, the client will see an error of "EIO".
82
83   32 vs 64 bit
84       It is likely that Perl plugins won't work well, or maybe won't work at
85       all, on 32 bit platforms.  This is simply because Perl doesn't have an
86       easy way to use 64 bit integers on 32 bit platforms, and 64 bit
87       integers (eg. file offsets, disk sizes) are required for many nbdkit
88       operations.
89
90   Perl callbacks
91       This just documents the arguments to the callbacks in Perl, and any way
92       that they differ from the C callbacks.  In all other respects they work
93       the same way as the C callbacks, so you should go and read
94       nbdkit-plugin(3).
95
96       "dump_plugin"
97           (Optional)
98
99           There are no arguments or return value.
100
101       "config"
102           (Optional)
103
104            sub config
105            {
106                my $key = shift;
107                my $value = shift;
108                # No return value.
109            }
110
111       "config_complete"
112           (Optional)
113
114           There are no arguments or return value.
115
116       "open"
117           (Required)
118
119            sub open
120            {
121                my $readonly = shift;
122                my $handle = {};
123                return $handle;
124            }
125
126           The "readonly" flag is a boolean.
127
128           You can return any Perl value as the handle.  It is passed back to
129           subsequent calls.  It's usually convenient to use a hashref, since
130           that lets you store arbitrary fields.
131
132       "close"
133           (Optional)
134
135            sub close
136            {
137                my $handle = shift;
138                # No return value
139            }
140
141           After "close" returns, the reference count of the handle is
142           decremented in the C part, which usually means that the handle and
143           its contents will be garbage collected.
144
145       "get_size"
146           (Required)
147
148            sub get_size
149            {
150                my $handle = shift;
151                my $i64 = .. the size of the disk ..;
152                return $i64;
153            }
154
155           This returns the size of the disk.  You can return any Perl object
156           that evaluates to an integer.
157
158       "can_write"
159           (Optional)
160
161            sub can_write
162            {
163                my $handle = shift;
164                my $bool = ...;
165                return $bool;
166            }
167
168           Return a boolean indicating whether the disk is writable.
169
170       "can_flush"
171           (Optional)
172
173            sub can_flush
174            {
175                my $handle = shift;
176                my $bool = ...;
177                return $bool;
178            }
179
180           Return a boolean indicating whether flush can be performed.
181
182       "is_rotational"
183           (Optional)
184
185            sub is_rotational
186            {
187                my $handle = shift;
188                my $bool = ...;
189                return $bool;
190            }
191
192           Return a boolean indicating whether the disk is rotational.
193
194       "can_trim"
195           (Optional)
196
197            sub can_trim
198            {
199                my $handle = shift;
200                my $bool = ...;
201                return $bool;
202            }
203
204           Return a boolean indicating whether trim/discard can be performed.
205
206       "pread"
207           (Required)
208
209            sub pread
210            {
211               my $handle = shift;
212               my $count = shift;
213               my $offset = shift;
214               # Construct a buffer of length $count bytes and return it.
215               return $buf;
216            }
217
218           The body of your "pread" function should construct a buffer of
219           length (at least) $count bytes.  You should read $count bytes from
220           the disk starting at $offset.
221
222           NBD only supports whole reads, so your function should try to read
223           the whole region (perhaps requiring a loop).  If the read fails or
224           is partial, your function should "die", optionally using
225           "Nbdkit::set_error" first.
226
227       "pwrite"
228           (Optional)
229
230            sub pwrite
231            {
232               my $handle = shift;
233               my $buf = shift;
234               my $count = length ($buf);
235               my $offset = shift;
236               # No return value
237            }
238
239           The body of your "pwrite" function should write the $buf string to
240           the disk.  You should write $count bytes to the disk starting at
241           $offset.
242
243           NBD only supports whole writes, so your function should try to
244           write the whole region (perhaps requiring a loop).  If the write
245           fails or is partial, your function should "die", optionally using
246           "Nbdkit::set_error" first.
247
248       "flush"
249           (Optional)
250
251            sub flush
252            {
253                my $handle = shift;
254                # No return value
255            }
256
257           The body of your "flush" function should do a sync(2) or
258           fdatasync(2) or equivalent on the backing store.
259
260           If there is an error, the function should call "die", optionally
261           using "Nbdkit::set_error" first.
262
263       "trim"
264           (Optional)
265
266            sub trim
267            {
268                my $handle = shift;
269                my $count = shift;
270                my $offset = shift;
271                # No return value
272            }
273
274           The body of your "trim" function should "punch a hole" in the
275           backing store.
276
277           If there is an error, the function should call "die", optionally
278           using "Nbdkit::set_error" first.
279
280       "zero"
281           (Optional)
282
283            sub zero
284            {
285               my $handle = shift;
286               my $count = shift;
287               my $offset = shift;
288               my $may_trim = shift;
289               # No return value
290            }
291
292           The body of your "zero" function should ensure that $count bytes of
293           the disk, starting at $offset, will read back as zero.  If
294           $may_trim is true, the operation may be optimized as a trim as long
295           as subsequent reads see zeroes.
296
297           NBD only supports whole writes, so your function should try to
298           write the whole region (perhaps requiring a loop).  If the write
299           fails or is partial, your function should "die", optionally using
300           "Nbdkit::set_error" first.  In particular, if you would like to
301           automatically fall back to "pwrite" (perhaps because there is
302           nothing to optimize if $may_trim is false), use
303           "Nbdkit::set_error(POSIX::EOPNOTSUPP)".
304
305   Missing callbacks
306       Missing: "load" and "unload"
307           These are not needed because you can just use regular Perl "BEGIN"
308           and "END" constructs.
309
310       Missing: "name", "version", "longname", "description", "config_help"
311           These are not yet supported.
312
313   Threads
314       The thread model for Perl callbacks currently cannot be set from Perl.
315       It is hard-coded in the C part to
316       "NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS".  This may change or be
317       settable in future.
318

SEE ALSO

320       nbdkit(1), nbdkit-plugin(3), perl(1).
321

AUTHORS

323       Eric Blake
324
325       Richard W.M. Jones
326
328       Copyright (C) 2013-2018 Red Hat Inc.
329

LICENSE

331       Redistribution and use in source and binary forms, with or without
332       modification, are permitted provided that the following conditions are
333       met:
334
335       ·   Redistributions of source code must retain the above copyright
336           notice, this list of conditions and the following disclaimer.
337
338       ·   Redistributions in binary form must reproduce the above copyright
339           notice, this list of conditions and the following disclaimer in the
340           documentation and/or other materials provided with the
341           distribution.
342
343       ·   Neither the name of Red Hat nor the names of its contributors may
344           be used to endorse or promote products derived from this software
345           without specific prior written permission.
346
347       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
348       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
349       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
350       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
351       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
352       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
353       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
354       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
355       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
356       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
357       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
358
359
360
361nbdkit-1.12.3                     2019-05-21             nbdkit-perl-plugin(3)
Impressum