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