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://gitlab.com/nbdkit/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   "Nbdkit::" functions
66       The following functions can be called in a virtual Perl package called
67       "Nbdkit".  Your script does not need to "use" this package, it is
68       already available in all scripts.
69
70       "Nbdkit::debug ($msg)"
71
72       In debugging mode, print $msg.  This is a wrapper around the C function
73       "nbdkit_debug" (see nbdkit-plugin(3)).
74
75       "Nbdkit::set_error ($err)"
76
77        Nbdkit::set_error($err);
78
79       Record $err as the reason you are about to throw an exception.  $err
80       should correspond to usual errno values, where it may help to "use
81       POSIX()".
82
83   Exceptions
84       Instead of returning error codes as in C, Perl callbacks should
85       indicate problems by throwing Perl exceptions (ie. "die", "croak" etc).
86       The Perl error message is captured and printed by nbdkit.  Remember to
87       use "Nbdkit::set_error" if you need to control which error is sent back
88       to the client; if omitted, the client will see an error of "EIO".
89
90   32 vs 64 bit
91       It is likely that Perl plugins won't work well, or maybe won't work at
92       all, on 32 bit platforms.  This is simply because Perl doesn't have an
93       easy way to use 64 bit integers on 32 bit platforms, and 64 bit
94       integers (eg. file offsets, disk sizes) are required for many nbdkit
95       operations.
96
97   Perl callbacks
98       This just documents the arguments to the callbacks in Perl, and any way
99       that they differ from the C callbacks.  In all other respects they work
100       the same way as the C callbacks, so you should go and read
101       nbdkit-plugin(3).
102
103       "dump_plugin"
104           (Optional)
105
106           There are no arguments or return value.
107
108       "config"
109           (Optional)
110
111            sub config
112            {
113                my $key = shift;
114                my $value = shift;
115                # No return value.
116            }
117
118       "config_complete"
119           (Optional)
120
121           There are no arguments or return value.
122
123       "open"
124           (Required)
125
126            sub open
127            {
128                my $readonly = shift;
129                my $handle = {};
130                return $handle;
131            }
132
133           The "readonly" flag is a boolean.
134
135           You can return any Perl value as the handle.  It is passed back to
136           subsequent calls.  It's usually convenient to use a hashref, since
137           that lets you store arbitrary fields.
138
139       "close"
140           (Optional)
141
142            sub close
143            {
144                my $handle = shift;
145                # No return value
146            }
147
148           After "close" returns, the reference count of the handle is
149           decremented in the C part, which usually means that the handle and
150           its contents will be garbage collected.
151
152       "get_size"
153           (Required)
154
155            sub get_size
156            {
157                my $handle = shift;
158                my $i64 = .. the size of the disk ..;
159                return $i64;
160            }
161
162           This returns the size of the disk.  You can return any Perl object
163           that evaluates to an integer.
164
165       "can_write"
166           (Optional)
167
168            sub can_write
169            {
170                my $handle = shift;
171                my $bool = ...;
172                return $bool;
173            }
174
175           Return a boolean indicating whether the disk is writable.
176
177       "can_flush"
178           (Optional)
179
180            sub can_flush
181            {
182                my $handle = shift;
183                my $bool = ...;
184                return $bool;
185            }
186
187           Return a boolean indicating whether flush can be performed.
188
189       "is_rotational"
190           (Optional)
191
192            sub is_rotational
193            {
194                my $handle = shift;
195                my $bool = ...;
196                return $bool;
197            }
198
199           Return a boolean indicating whether the disk is rotational.
200
201       "can_trim"
202           (Optional)
203
204            sub can_trim
205            {
206                my $handle = shift;
207                my $bool = ...;
208                return $bool;
209            }
210
211           Return a boolean indicating whether trim/discard can be performed.
212
213       "pread"
214           (Required)
215
216            sub pread
217            {
218               my $handle = shift;
219               my $count = shift;
220               my $offset = shift;
221               my $flags = shift;
222               # Construct a buffer of length $count bytes and return it.
223               return $buf;
224            }
225
226           The body of your "pread" function should construct a buffer of
227           length (at least) $count bytes.  You should read $count bytes from
228           the disk starting at $offset.
229
230           NBD only supports whole reads, so your function should try to read
231           the whole region (perhaps requiring a loop).  If the read fails or
232           is partial, your function should "die", optionally using
233           "Nbdkit::set_error" first.
234
235       "pwrite"
236           (Optional)
237
238            sub pwrite
239            {
240               my $handle = shift;
241               my $buf = shift;
242               my $count = length ($buf);
243               my $offset = shift;
244               my $flags = shift;
245               # No return value
246            }
247
248           The body of your "pwrite" function should write the $buf string to
249           the disk.  You should write $count bytes to the disk starting at
250           $offset.
251
252           NBD only supports whole writes, so your function should try to
253           write the whole region (perhaps requiring a loop).  If the write
254           fails or is partial, your function should "die", optionally using
255           "Nbdkit::set_error" first.
256
257       "flush"
258           (Optional)
259
260            sub flush
261            {
262               my $handle = shift;
263               my $flags = shift;
264               # No return value
265            }
266
267           The body of your "flush" function should do a sync(2) or
268           fdatasync(2) or equivalent on the backing store.
269
270           If there is an error, the function should call "die", optionally
271           using "Nbdkit::set_error" first.
272
273       "trim"
274           (Optional)
275
276            sub trim
277            {
278               my $handle = shift;
279               my $count = shift;
280               my $offset = shift;
281               my $flags = shift;
282               # No return value
283            }
284
285           The body of your "trim" function should "punch a hole" in the
286           backing store.
287
288           If there is an error, the function should call "die", optionally
289           using "Nbdkit::set_error" first.
290
291       "zero"
292           (Optional)
293
294            sub zero
295            {
296               my $handle = shift;
297               my $count = shift;
298               my $offset = shift;
299               my $flags = shift;
300               # No return value
301            }
302
303           The body of your "zero" function should ensure that $count bytes of
304           the disk, starting at $offset, will read back as zero.
305
306           NBD only supports whole writes, so your function should try to
307           write the whole region (perhaps requiring a loop).  If the write
308           fails or is partial, your function should "die", optionally using
309           "Nbdkit::set_error" first.  In particular, if you would like to
310           automatically fall back to "pwrite" (perhaps because there is
311           nothing to optimize if $flags does not contain
312           $Nbdkit::FLAG_MAY_TRIM), use Nbdkit::set_error(POSIX::EOPNOTSUPP).
313
314   Missing callbacks
315       Missing: "load" and "unload"
316           These are not needed because you can just use regular Perl "BEGIN"
317           and "END" constructs.
318
319       Missing: "name", "version", "longname", "description", "config_help",
320       "can_fua", "can_cache", "cache"
321           These are not yet supported.
322
323   Threads
324       The thread model for Perl callbacks currently cannot be set from Perl.
325       It is hard-coded in the C part to
326       "NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS".  This may change or be
327       settable in future.
328

FILES

330       $plugindir/nbdkit-perl-plugin.so
331           The plugin.
332
333           Use "nbdkit --dump-config" to find the location of $plugindir.
334

VERSION

336       "nbdkit-perl-plugin" first appeared in nbdkit 1.2.
337

SEE ALSO

339       nbdkit(1), nbdkit-plugin(3), perl(1).
340

AUTHORS

342       Eric Blake
343
344       Richard W.M. Jones
345
347       Copyright Red Hat
348

LICENSE

350       Redistribution and use in source and binary forms, with or without
351       modification, are permitted provided that the following conditions are
352       met:
353
354       •   Redistributions of source code must retain the above copyright
355           notice, this list of conditions and the following disclaimer.
356
357       •   Redistributions in binary form must reproduce the above copyright
358           notice, this list of conditions and the following disclaimer in the
359           documentation and/or other materials provided with the
360           distribution.
361
362       •   Neither the name of Red Hat nor the names of its contributors may
363           be used to endorse or promote products derived from this software
364           without specific prior written permission.
365
366       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
367       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
368       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
369       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
370       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
371       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
372       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
373       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
374       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
375       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
376       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
377
378
379
380nbdkit-1.34.4                     2023-09-26             nbdkit-perl-plugin(3)
Impressum