1nbdkit-perl-plugin(3) NBDKIT nbdkit-perl-plugin(3)
2
3
4
6 nbdkit-perl-plugin - nbdkit perl plugin
7
9 nbdkit perl /path/to/plugin.pl [arguments...]
10
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
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 "can_fua", "can_cache", "cache"
312 These are not yet supported.
313
314 Threads
315 The thread model for Perl callbacks currently cannot be set from Perl.
316 It is hard-coded in the C part to
317 "NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS". This may change or be
318 settable in future.
319
321 $plugindir/nbdkit-perl-plugin.so
322 The plugin.
323
324 Use "nbdkit --dump-config" to find the location of $plugindir.
325
327 "nbdkit-perl-plugin" first appeared in nbdkit 1.2.
328
330 nbdkit(1), nbdkit-plugin(3), perl(1).
331
333 Eric Blake
334
335 Richard W.M. Jones
336
338 Copyright (C) 2013-2018 Red Hat Inc.
339
341 Redistribution and use in source and binary forms, with or without
342 modification, are permitted provided that the following conditions are
343 met:
344
345 · Redistributions of source code must retain the above copyright
346 notice, this list of conditions and the following disclaimer.
347
348 · Redistributions in binary form must reproduce the above copyright
349 notice, this list of conditions and the following disclaimer in the
350 documentation and/or other materials provided with the
351 distribution.
352
353 · Neither the name of Red Hat nor the names of its contributors may
354 be used to endorse or promote products derived from this software
355 without specific prior written permission.
356
357 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
358 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
359 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
360 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
361 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
362 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
363 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
364 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
365 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
366 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
367 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
368
369
370
371nbdkit-1.18.4 2020-04-16 nbdkit-perl-plugin(3)