1nbdkit-perl-plugin(3) NBDKIT nbdkit-perl-plugin(3)
2
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 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 nbdkit perl /path/to/plugin.pl
20 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 Broadly speaking, Perl nbdkit plugins work like C ones, so you should
29 read nbdkit-plugin(3) first.
30 To write a Perl nbdkit plugin, you create a Perl file which contains at
32 least the following required subroutines:
33 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 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 Executable script
55 If you want you can make the script executable and include a "shebang"
56 at the top:
57 #!/usr/sbin/nbdkit perl
59 See also "Shebang scripts" in nbdkit(1).
61 These scripts can also be installed in the $plugindir. See "WRITING
63 PLUGINS IN OTHER PROGRAMMING LANGUAGES" in nbdkit-plugin(3).
64 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 Nbdkit::set_error($err);
71 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 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 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 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 "dump_plugin"
97 (Optional)
98 There are no arguments or return value.
100 "config"
102 (Optional)
103 sub config
105 {
106 my $key = shift;
107 my $value = shift;
108 # No return value.
109 }
110 "config_complete"
112 (Optional)
113 There are no arguments or return value.
115 "open"
117 (Required)
118 sub open
120 {
121 my $readonly = shift;
122 my $handle = {};
123 return $handle;
124 }
125 The "readonly" flag is a boolean.
127 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 "close"
133 (Optional)
134 sub close
136 {
137 my $handle = shift;
138 # No return value
139 }
140 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 "get_size"
146 (Required)
147 sub get_size
149 {
150 my $handle = shift;
151 my $i64 = .. the size of the disk ..;
152 return $i64;
153 }
154 This returns the size of the disk. You can return any Perl object
156 that evaluates to an integer.
157 "can_write"
159 (Optional)
160 sub can_write
162 {
163 my $handle = shift;
164 my $bool = ...;
165 return $bool;
166 }
167 Return a boolean indicating whether the disk is writable.
169 "can_flush"
171 (Optional)
172 sub can_flush
174 {
175 my $handle = shift;
176 my $bool = ...;
177 return $bool;
178 }
179 Return a boolean indicating whether flush can be performed.
181 "is_rotational"
183 (Optional)
184 sub is_rotational
186 {
187 my $handle = shift;
188 my $bool = ...;
189 return $bool;
190 }
191 Return a boolean indicating whether the disk is rotational.
193 "can_trim"
195 (Optional)
196 sub can_trim
198 {
199 my $handle = shift;
200 my $bool = ...;
201 return $bool;
202 }
203 Return a boolean indicating whether trim/discard can be performed.
205 "pread"
207 (Required)
208 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 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 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 "pwrite"
228 (Optional)
229 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 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 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 "flush"
249 (Optional)
250 sub flush
252 {
253 my $handle = shift;
254 # No return value
255 }
256 The body of your "flush" function should do a sync(2) or
258 fdatasync(2) or equivalent on the backing store.
259 If there is an error, the function should call "die", optionally
261 using "Nbdkit::set_error" first.
262 "trim"
264 (Optional)
265 sub trim
267 {
268 my $handle = shift;
269 my $count = shift;
270 my $offset = shift;
271 # No return value
272 }
273 The body of your "trim" function should "punch a hole" in the
275 backing store.
276 If there is an error, the function should call "die", optionally
278 using "Nbdkit::set_error" first.
279 "zero"
281 (Optional)
282 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 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 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 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 Missing: "name", "version", "longname", "description", "config_help",
311 "can_fua", "can_cache", "cache"
312 These are not yet supported.
313 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 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 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 · Redistributions of source code must retain the above copyright
346 notice, this list of conditions and the following disclaimer.
347 · 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 · 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 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.
368nbdkit-1.16.1 2019-12-03 nbdkit-perl-plugin(3)