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://gitlab.com/nbdkit/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 "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 "Nbdkit::debug ($msg)"
71 In debugging mode, print $msg. This is a wrapper around the C function
73 "nbdkit_debug" (see nbdkit-plugin(3)).
74 "Nbdkit::set_error ($err)"
76 Nbdkit::set_error($err);
78 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 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 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 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 "dump_plugin"
104 (Optional)
105 There are no arguments or return value.
107 "config"
109 (Optional)
110 sub config
112 {
113 my $key = shift;
114 my $value = shift;
115 # No return value.
116 }
117 "config_complete"
119 (Optional)
120 There are no arguments or return value.
122 "open"
124 (Required)
125 sub open
127 {
128 my $readonly = shift;
129 my $handle = {};
130 return $handle;
131 }
132 The "readonly" flag is a boolean.
134 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 "close"
140 (Optional)
141 sub close
143 {
144 my $handle = shift;
145 # No return value
146 }
147 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 "get_size"
153 (Required)
154 sub get_size
156 {
157 my $handle = shift;
158 my $i64 = .. the size of the disk ..;
159 return $i64;
160 }
161 This returns the size of the disk. You can return any Perl object
163 that evaluates to an integer.
164 "can_write"
166 (Optional)
167 sub can_write
169 {
170 my $handle = shift;
171 my $bool = ...;
172 return $bool;
173 }
174 Return a boolean indicating whether the disk is writable.
176 "can_flush"
178 (Optional)
179 sub can_flush
181 {
182 my $handle = shift;
183 my $bool = ...;
184 return $bool;
185 }
186 Return a boolean indicating whether flush can be performed.
188 "is_rotational"
190 (Optional)
191 sub is_rotational
193 {
194 my $handle = shift;
195 my $bool = ...;
196 return $bool;
197 }
198 Return a boolean indicating whether the disk is rotational.
200 "can_trim"
202 (Optional)
203 sub can_trim
205 {
206 my $handle = shift;
207 my $bool = ...;
208 return $bool;
209 }
210 Return a boolean indicating whether trim/discard can be performed.
212 "pread"
214 (Required)
215 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 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 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 "pwrite"
236 (Optional)
237 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 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 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 "flush"
258 (Optional)
259 sub flush
261 {
262 my $handle = shift;
263 my $flags = shift;
264 # No return value
265 }
266 The body of your "flush" function should do a sync(2) or
268 fdatasync(2) or equivalent on the backing store.
269 If there is an error, the function should call "die", optionally
271 using "Nbdkit::set_error" first.
272 "trim"
274 (Optional)
275 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 The body of your "trim" function should "punch a hole" in the
286 backing store.
287 If there is an error, the function should call "die", optionally
289 using "Nbdkit::set_error" first.
290 "zero"
292 (Optional)
293 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 The body of your "zero" function should ensure that $count bytes of
304 the disk, starting at $offset, will read back as zero.
305 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 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 Missing: "name", "version", "longname", "description", "config_help",
320 "can_fua", "can_cache", "cache"
321 These are not yet supported.
322 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
330 $plugindir/nbdkit-perl-plugin.so
331 The plugin.
332 Use "nbdkit --dump-config" to find the location of $plugindir.
334
336 "nbdkit-perl-plugin" first appeared in nbdkit 1.2.
337
339 nbdkit(1), nbdkit-plugin(3), perl(1).
340
342 Eric Blake
343 Richard W.M. Jones
345
347 Copyright Red Hat
348
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 • Redistributions of source code must retain the above copyright
355 notice, this list of conditions and the following disclaimer.
356 • 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 • 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 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.
377nbdkit-1.34.4 2023-09-26 nbdkit-perl-plugin(3)