plugins/tcl/nbdkit-tcl-plugin.pod

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