plugins/perl/nbdkit-perl-plugin.pod

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