plugins/lua/nbdkit-lua-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-lua-plugin - nbdkit Lua plugin
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit lua /path/to/plugin.lua [arguments...]
   8
   9 =head1 DESCRIPTION
  10
  11 C<nbdkit-lua-plugin> is an embedded Lua interpreter for
  12 L<nbdkit(1)>, allowing you to write nbdkit plugins in Lua.
  13
  14 =head2 If you have been given an nbdkit Lua plugin
  15
  16 Assuming you have a Lua script which is an nbdkit plugin, you run it
  17 like this:
  18
  19  nbdkit lua /path/to/plugin.lua
  20
  21 You may have to add further C<key=value> arguments to the command
  22 line.  Read the Lua script to see if it requires any.
  23
  24 =head1 WRITING A LUA NBDKIT PLUGIN
  25
  26 For an example plugin written in Lua, see:
  27 L<https://gitlab.com/nbdkit/nbdkit/blob/master/plugins/lua/example.lua>
  28
  29 Broadly speaking, Lua nbdkit plugins work like C ones, so you should
  30 read L<nbdkit-plugin(3)> first.
  31
  32 To write a Lua nbdkit plugin, you create a Lua file which contains
  33 at least the following required functions:
  34
  35  function open (readonly)
  36      -- see below
  37      return h
  38  end
  39  function get_size (h)
  40      -- see below
  41      return size
  42  end
  43  function pread (h, count, offset)
  44      -- see below
  45      return buf
  46  end
  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 are run when
  52 nbdkit starts up.
  53
  54 =head2 Executable script
  55
  56 If you want you can make the script executable and include a "shebang"
  57 at the top:
  58
  59  #!/usr/sbin/nbdkit lua
  60
  61 See also L<nbdkit(1)/Shebang scripts>.
  62
  63 These scripts can also be installed in the C<$plugindir>.  See
  64 L<nbdkit-plugin(3)/WRITING PLUGINS IN OTHER PROGRAMMING LANGUAGES>.
  65
  66 =head2 Errors
  67
  68 Lua plugin methods can indicate an error by calling C<error> or
  69 C<assert>.  The error message will contain the method name, filename
  70 and line number where the error occurred, eg:
  71
  72  error ("could not open " .. filename)
  73  --> nbdkit: error: open: myplugin.lua:123: could not open disk.img
  74
  75 =head2 Lua callbacks
  76
  77 This just documents the arguments to the callbacks in Lua, and any
  78 way that they differ from the C callbacks.  In all other respects they
  79 work the same way as the C callbacks, so you should go and read
  80 L<nbdkit-plugin(3)>.
  81
  82 =over 4
  83
  84 =item C<dump_plugin>
  85
  86 (Optional)
  87
  88 There are no arguments or return value.
  89
  90 =item C<config>
  91
  92 (Optional)
  93
  94  function config (key, value)
  95      -- No return value.
  96  end
  97
  98 =item C<config_complete>
  99
 100 (Optional)
 101
 102 There are no arguments or return value.
 103
 104 =item C<open>
 105
 106 (Required)
 107
 108  function open (readonly)
 109      local handle
 110      handle=...
 111      return handle
 112  end
 113
 114 The C<readonly> flag is a boolean.
 115
 116 You can return any Lua string or object as the handle.  It is passed
 117 back to subsequent calls.
 118
 119 =item C<close>
 120
 121 (Optional)
 122
 123  function close (h)
 124      -- No return value
 125  end
 126
 127 After C<close> returns, the reference count of the handle is
 128 decremented in the C part, which usually means that the handle and its
 129 contents will be garbage collected.
 130
 131 =item C<get_size>
 132
 133 (Required)
 134
 135  function get_size (h)
 136      local size
 137      size= .. the size of the disk ..
 138      return size
 139  end
 140
 141 This returns the size of the disk.
 142
 143 =item C<can_write>
 144
 145 (Optional)
 146
 147  function can_write (h)
 148      return bool
 149  end
 150
 151 Return a boolean indicating whether the disk is writable.
 152
 153 =item C<can_flush>
 154
 155 (Optional)
 156
 157  function can_flush (h)
 158      return bool
 159  end
 160
 161 Return a boolean indicating whether flush can be performed.
 162
 163 =item C<is_rotational>
 164
 165 (Optional)
 166
 167  function is_rotational (h)
 168      return bool
 169  end
 170
 171 Return a boolean indicating whether the disk is rotational.
 172
 173 =item C<can_trim>
 174
 175 (Optional)
 176
 177  function can_trim (h)
 178      return bool
 179  end
 180
 181 Return a boolean indicating whether trim/discard can be performed.
 182
 183 =item C<pread>
 184
 185 (Required)
 186
 187  function pread (h, count, offset)
 188     -- Construct a buffer of length count bytes and return it.
 189     return buf
 190  end
 191
 192 The body of your C<pread> function should construct a buffer of length
 193 (at least) C<count> bytes.  You should read C<count> bytes from the
 194 disk starting at C<offset>.
 195
 196 NBD only supports whole reads, so your function should try to read the
 197 whole region (perhaps requiring a loop).  If the read fails or is
 198 partial, your function should call C<error>.
 199
 200 =item C<pwrite>
 201
 202 (Optional)
 203
 204  function pwrite (h, buf, offset)
 205     -- No return value
 206  end
 207
 208 The body of your C<pwrite> function should write the C<buf> string to
 209 the disk.  You should write C<count> bytes to the disk starting at
 210 C<offset>.
 211
 212 NBD only supports whole writes, so your function should try to write
 213 the whole region (perhaps requiring a loop).  If the write fails or is
 214 partial, your function should call C<error>.
 215
 216 =item C<flush>
 217
 218 (Optional)
 219
 220  function flush (h)
 221      -- No return value
 222  end
 223
 224 The body of your C<flush> function should do a L<sync(2)> or
 225 L<fdatasync(2)> or equivalent on the backing store.
 226
 227 =item C<trim>
 228
 229 (Optional)
 230
 231  function trim (h, count, offset)
 232      -- No return value
 233  end
 234
 235 The body of your C<trim> function should "punch a hole" in the backing
 236 store.
 237
 238 =item C<zero>
 239
 240 (Optional)
 241
 242  function zero (h, count, offset, may_trim)
 243     -- No return value
 244  end
 245
 246 The body of your C<zero> function should ensure that C<count> bytes
 247 of the disk, starting at C<offset>, will read back as zero.  If
 248 C<may_trim> is true, the operation may be optimized as a trim as long
 249 as subsequent reads see zeroes.
 250
 251 NBD only supports whole writes, so your function should try to write
 252 the whole region (perhaps requiring a loop).  If the write fails or is
 253 partial, your function should call C<error>.
 254
 255 =back
 256
 257 =head2 Missing callbacks
 258
 259 =over 4
 260
 261 =item Missing: C<load>, C<unload>, C<name>, C<version>, C<longname>,
 262 C<description>, C<config_help>, C<can_zero>, C<can_fua>, C<can_cache>,
 263 C<cache>
 264
 265 These are not yet supported.
 266
 267 =back
 268
 269 =head2 Threads
 270
 271 The thread model for Lua callbacks currently cannot be set from Lua.
 272 It is hard-coded in the C part to
 273 C<NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS>.  This may change or be
 274 settable in future.
 275
 276 =head1 FILES
 277
 278 =over 4
 279
 280 =item F<$plugindir/nbdkit-lua-plugin.so>
 281
 282 The plugin.
 283
 284 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
 285
 286 =back
 287
 288 =head1 VERSION
 289
 290 C<nbdkit-lua-plugin> first appeared in nbdkit 1.6.
 291
 292 =head1 SEE ALSO
 293
 294 L<nbdkit(1)>,
 295 L<nbdkit-plugin(3)>.
 296
 297 =head1 AUTHORS
 298
 299 Richard W.M. Jones
 300
 301 =head1 COPYRIGHT
 302
 303 Copyright Red Hat