tests: Make all guestfish tests use runtime check.
[nbdkit/ericb.git] / docs / nbdkit-plugin.pod
blob0afd5e1fcc9b363f9796803c27a16ba382053dc2
1 =head1 NAME
3 nbdkit-plugin - how to write nbdkit plugins
5 =head1 SYNOPSIS
7  #define NBDKIT_API_VERSION 2
8  
9  #include <nbdkit-plugin.h>
11  #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
13  static void *
14  myplugin_open (void)
15  {
16    /* create a handle ... */
17    return handle;
18  }
20  static struct nbdkit_plugin plugin = {
21    .name              = "myplugin",
22    .open              = myplugin_open,
23    .get_size          = myplugin_get_size,
24    .pread             = myplugin_pread,
25    .pwrite            = myplugin_pwrite,
26    /* etc */
27  };
29  NBDKIT_REGISTER_PLUGIN(plugin)
31 When this has been compiled to a shared library, do:
33  nbdkit [--args ...] ./myplugin.so [key=value ...]
35 When debugging, use the I<-fv> options:
37  nbdkit -fv ./myplugin.so [key=value ...]
39 =head1 DESCRIPTION
41 An nbdkit plugin is a new source device which can be served using the
42 Network Block Device (NBD) protocol.  This manual page describes how
43 to create an nbdkit plugin in C.
45 To see example plugins:
46 L<https://github.com/libguestfs/nbdkit/tree/master/plugins>
48 Plugins written in C have an ABI guarantee: a plugin compiled against
49 an older version of nbdkit will still work correctly when loaded with
50 a newer nbdkit.  We also try (but cannot guarantee) to support plugins
51 compiled against a newer version of nbdkit when loaded with an older
52 nbdkit, although the plugin may have reduced functionality if it
53 depends on features only provided by newer nbdkit.
55 For plugins written in C, we also provide an API guarantee: a plugin
56 written against an older header will still compile unmodified with a
57 newer nbdkit.
59 The API guarantee does not always apply to plugins written in other
60 (non-C) languages which may have to adapt to changes when recompiled
61 against a newer nbdkit.
63 To write plugins in other languages, see:
64 __LANG_PLUGIN_LINKS__.
66 =head1 C<#define NBDKIT_API_VERSION 2>
68 Plugins must choose which API version they want to use, by defining
69 NBDKIT_API_VERSION to a positive integer prior to including
70 C<nbdkit-plugin.h> (or any other nbdkit header).  The default version
71 is 1 for backwards-compatibility with nbdkit v1.1.26 and earlier;
72 however, it is recommended that new plugins be written to the maximum
73 version (currently 2) as it enables more features and better
74 interaction with nbdkit filters.  Therefore, the rest of this document
75 only covers the version 2 interface.  A newer nbdkit will always
76 support plugins written in C which were compiled against any prior API
77 version.
79 =head1 C<#include E<lt>nbdkit-plugin.hE<gt>>
81 All plugins should start by including this header file, after
82 optionally choosing an API version.
84 =head1 C<#define THREAD_MODEL>
86 All plugins must define a thread model.  See L</THREADS> below for
87 details.  It is generally safe to use:
89  #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
91 =head1 C<struct nbdkit_plugin>
93 All plugins must define and register one C<struct nbdkit_plugin>,
94 which contains the name of the plugin and pointers to callback
95 functions.
97  static struct nbdkit_plugin plugin = {
98    .name              = "myplugin",
99    .longname          = "My Plugin",
100    .description       = "This is my great plugin for nbdkit",
101    .open              = myplugin_open,
102    .get_size          = myplugin_get_size,
103    .pread             = myplugin_pread,
104    .pwrite            = myplugin_pwrite,
105    /* etc */
106  };
108  NBDKIT_REGISTER_PLUGIN(plugin)
110 The C<.name> field is the name of the plugin.
112 The callbacks are described below (see L</CALLBACKS>).  Only C<.name>,
113 C<.open>, C<.get_size> and C<.pread> are required.  All other
114 callbacks can be omitted.  However almost all plugins should have a
115 C<.close> callback.  Most real-world plugins will also want to declare
116 some of the other callbacks.
118 The nbdkit server calls the callbacks in the following order over the
119 lifetime of the plugin:
121 =over 4
123 =item C<.load>
125 is called once just after the plugin is loaded into memory.
127 =item C<.config> and C<.config_complete>
129 C<.config> is called zero or more times during command line parsing.
130 C<.config_complete> is called once after all configuration information
131 has been passed to the plugin (but not during C<nbdkit --dump-plugin>).
133 Both are called after loading the plugin but before any connections
134 are accepted.
136 =item C<.thread_model>
138 In normal operation, C<.thread_model> is called once after
139 C<.config_complete> has validated all configuration information, and
140 before any connections are accepted.  However, during C<nbdkit
141 --dump-plugin>, it is called after any C<.config> calls but without
142 C<.config_complete> (so a plugin which determines the results from a
143 script must be prepared for a missing script).
145 =item C<.open>
147 A new client has connected.
149 =item C<.can_write>, C<.get_size> and other option negotiation callbacks
151 These are called during option negotiation with the client, but before
152 any data is served.  These callbacks may return different values
153 across different C<.open> calls, but within a single connection, they
154 are called at most once and cached by nbdkit for that connection.
156 =item C<.pread>, C<.pwrite> and other data serving callbacks
158 After option negotiation has finished, these may be called to serve
159 data.  Depending on the thread model chosen, they might be called in
160 parallel from multiple threads.  The data serving callbacks include a
161 flags argument; the results of the negotiation callbacks influence
162 whether particular flags will ever be passed to a data callback.
164 =item C<.close>
166 The client has disconnected.
168 =item C<.open> ... C<.close>
170 The sequence C<.open> ... C<.close> can be called repeatedly over the
171 lifetime of the plugin, and can be called in parallel (depending on
172 the thread model).
174 =item C<.unload>
176 is called once just before the plugin is unloaded from memory.
178 =back
180 =head1 FLAGS
182 The following flags are defined by nbdkit, and used in various data
183 serving callbacks as follows:
185 =over 4
187 =item C<NBDKIT_FLAG_MAY_TRIM>
189 This flag is used by the C<.zero> callback; there is no way to disable
190 this flag, although a plugin that does not support trims as a way to
191 write zeroes may ignore the flag without violating expected semantics.
193 =item C<NBDKIT_FLAG_FUA>
195 This flag represents Forced Unit Access semantics.  It is used by the
196 C<.pwrite>, C<.zero>, and C<.trim> callbacks to indicate that the
197 plugin must not return a result until the action has landed in
198 persistent storage.  This flag will not be sent to the plugin unless
199 C<.can_fua> is provided and returns C<NBDKIT_FUA_NATIVE>.
201 =back
203 The following defines are valid as successful return values for
204 C<.can_fua>:
206 =over 4
208 =item C<NBDKIT_FUA_NONE>
210 Forced Unit Access is not supported; the client must manually request
211 a flush after writes have completed.  The C<NBDKIT_FLAG_FUA> flag will
212 not be passed to the plugin's write callbacks.
214 =item C<NBDKIT_FUA_EMULATE>
216 The client may request Forced Unit Access, but it is implemented by
217 emulation, where nbdkit calls C<.flush> after a write operation; this
218 is semantically correct, but may hurt performance as it tends to flush
219 more data than just what the client requested.  The C<NBDKIT_FLAG_FUA>
220 flag will not be passed to the plugin's write callbacks.
222 =item C<NBDKIT_FUA_NATIVE>
224 The client may request Forced Unit Access, which results in the
225 C<NBDKIT_FLAG_FUA> flag being passed to the plugin's write callbacks
226 (C<.pwrite>, C<.trim>, and C<.zero>).  When the flag is set, these
227 callbacks must not return success until the client's request has
228 landed in persistent storage.
230 =back
232 The following defines are valid as successful return values for
233 C<.can_cache>:
235 =over 4
237 =item C<NBDKIT_CACHE_NONE>
239 The server does not advertise caching support, and rejects any
240 client-requested caching. Any C<.cache> callback is ignored.
242 =item C<NBDKIT_CACHE_EMULATE>
244 The nbdkit server advertises cache support to the client, where the
245 client may request that the server cache a region of the export to
246 potentially speed up future read and/or write operations on that
247 region. The nbdkit server implements the caching by calling C<.pread>
248 and ignoring the results. This option exists to ease the
249 implementation of a common form of caching; any C<.cache> callback is
250 ignored.
252 =item C<NBDKIT_CACHE_NATIVE>
254 The nbdkit server advertises cache support to the client, where the
255 client may request that the server cache a region of the export to
256 potentially speed up future read and/or write operations on that
257 region. The nbdkit server calls the C<.cache> callback to perform the
258 caching; if that callback is missing, the client's cache request
259 succeeds without doing anything.
261 =back
263 =head1 ERROR HANDLING
265 If there is an error in the plugin, the plugin should call
266 C<nbdkit_error> to report an error message; additionally, if the
267 callback is involved in serving data, the plugin should call
268 C<nbdkit_set_error> to influence the error code that will be sent to
269 the client.  These two functions can be called in either order.  Then,
270 the callback should return the appropriate error indication,
271 eg. C<NULL> or C<-1>.
273 If the call to C<nbdkit_set_error> is omitted while serving data, then
274 the global variable C<errno> may be used.  For plugins which have
275 C<.errno_is_preserved != 0> the core code will use C<errno>.  In
276 plugins written in non-C languages, we usually cannot trust that
277 C<errno> will not be overwritten when returning from that language to
278 C.  In that case, either the plugin must call C<nbdkit_set_error> or
279 hard-coded C<EIO> is used.
281 C<nbdkit_error> has the following prototype and works like
282 L<printf(3)>:
284  void nbdkit_error (const char *fs, ...);
285  void nbdkit_verror (const char *fs, va_list args);
287 For convenience, C<nbdkit_error> preserves the value of C<errno>, and
288 also supports the glibc extension of a single C<%m> in a format string
289 expanding to C<strerror(errno)>, even on platforms that don't support
290 that natively.
292 C<nbdkit_set_error> can be called at any time, but only has an impact
293 during callbacks for serving data, and only when the callback returns
294 an indication of failure.  It has the following prototype:
296  void nbdkit_set_error (int err);
298 =head1 CALLBACKS
300 =head2 C<.name>
302  const char *name;
304 This field (a string) is required, and B<must> contain only ASCII
305 alphanumeric characters and be unique amongst all plugins.
307 =head2 C<.version>
309  const char *version;
311 Plugins may optionally set a version string which is displayed in help
312 and debugging output.
314 =head2 C<.longname>
316  const char *longname;
318 An optional free text name of the plugin.  This field is used in error
319 messages.
321 =head2 C<.description>
323  const char *description;
325 An optional multi-line description of the plugin.
327 =head2 C<.load>
329  void load (void);
331 This is called once just after the plugin is loaded into memory.  You
332 can use this to perform any global initialization needed by the
333 plugin.
335 =head2 C<.unload>
337  void unload (void);
339 This may be called once just before the plugin is unloaded from
340 memory.  Note that it's not guaranteed that C<.unload> will always be
341 called (eg. the server might be killed or segfault), so you should try
342 to make the plugin as robust as possible by not requiring cleanup.
343 See also L</SHUTDOWN> below.
345 =head2 C<.dump_plugin>
347  void dump_plugin (void);
349 This optional callback is called when the
350 S<C<nbdkit plugin --dump-plugin>> command is used.  It should print
351 any additional informative C<key=value> fields to stdout as needed.
352 Prefixing the keys with the name of the plugin will avoid conflicts.
354 =head2 C<.config>
356  int config (const char *key, const char *value);
358 On the nbdkit command line, after the plugin filename, come an
359 optional list of C<key=value> arguments.  These are passed to the
360 plugin through this callback when the plugin is first loaded and
361 before any connections are accepted.
363 This callback may be called zero or more times.
365 Both C<key> and C<value> parameters will be non-NULL.  The strings are
366 owned by nbdkit but will remain valid for the lifetime of the plugin,
367 so the plugin does not need to copy them.
369 The key will be a non-empty string beginning with an ASCII alphabetic
370 character (C<A-Z> C<a-z>).  The rest of the key must contain only
371 ASCII alphanumeric plus period, underscore or dash characters (C<A-Z>
372 C<a-z> C<0-9> C<.> C<_> C<->).  The value may be an arbitrary string,
373 including an empty string.
375 The names of C<key>s accepted by plugins is up to the plugin, but you
376 should probably look at other plugins and follow the same conventions.
378 If the value is a relative path, then note that the server changes
379 directory when it starts up.  See L</FILENAMES AND PATHS> above.
381 If the C<.config> callback is not provided by the plugin, and the user
382 tries to specify any C<key=value> arguments, then nbdkit will exit
383 with an error.
385 If there is an error, C<.config> should call C<nbdkit_error> with an
386 error message and return C<-1>.
388 =head2 C<.magic_config_key>
390  const char *magic_config_key;
392 This optional string can be used to set a "magic" key used when
393 parsing plugin parameters.  It affects how "bare parameters" (those
394 which do not contain an C<=> character) are parsed on the command
395 line.
397 If C<magic_config_key != NULL> then any bare parameters are passed to
398 the C<.config> method as: S<C<config (magic_config_key, argv[i]);>>.
400 If C<magic_config_key> is not set then we behave as in nbdkit E<lt>
401 1.7: If the first parameter on the command line is bare then it is
402 passed to the C<.config> method as: S<C<config ("script", value);>>.
403 Any other bare parameters give errors.
405 =head2 C<.config_complete>
407  int config_complete (void);
409 This optional callback is called after all the configuration has been
410 passed to the plugin.  It is a good place to do checks, for example
411 that the user has passed the required parameters to the plugin.
413 If there is an error, C<.config_complete> should call C<nbdkit_error>
414 with an error message and return C<-1>.
416 =head2 C<.config_help>
418  const char *config_help;
420 This optional multi-line help message should summarize any
421 C<key=value> parameters that it takes.  It does I<not> need to repeat
422 what already appears in C<.description>.
424 If the plugin doesn't take any config parameters you should probably
425 omit this.
427 =head2 C<.thread_model>
429  int thread_model (void)
431 This optional callback is called after all the configuration has been
432 passed to the plugin.  It can be used to force a stricter thread model
433 based on configuration, compared to C<THREAD_MODEL>.  See L</THREADS>
434 below for details.  Attempts to request a looser (more parallel) model
435 are silently ignored.
437 If there is an error, C<.thread_model> should call C<nbdkit_error>
438 with an error message and return C<-1>.
440 =head2 C<.open>
442  void *open (int readonly);
444 This is called when a new client connects to the nbdkit server.  The
445 callback should allocate a handle and return it.  This handle
446 is passed back to other callbacks and could be freed in the C<.close>
447 callback.
449 Note that the handle is completely opaque to nbdkit, but it must not
450 be NULL.  If you don't need to use a handle, return
451 C<NBDKIT_HANDLE_NOT_NEEDED> which is a static non-NULL pointer.
453 The C<readonly> flag informs the plugin that the user requested a
454 read-only connection using the I<-r> flag on the command line.  Note
455 that the plugin may I<additionally> force the connection to be
456 readonly (even if this flag is false) by returning false from the
457 C<.can_write> callback.  So if your plugin can only serve read-only,
458 you can ignore this parameter.
460 If there is an error, C<.open> should call C<nbdkit_error> with an
461 error message and return C<NULL>.
463 =head2 C<.close>
465  void close (void *handle);
467 This is called when the client closes the connection.  It should clean
468 up any per-connection resources.
470 Note there is no way in the NBD protocol to communicate close errors
471 back to the client, for example if your plugin calls L<close(2)> and
472 you are checking for errors (as you should do).  Therefore the best
473 you can do is to log the error on the server.  Well-behaved NBD
474 clients I<should> try to flush the connection before it is closed and
475 check for errors, but obviously this is outside the scope of nbdkit.
477 =head2 C<.get_size>
479  int64_t get_size (void *handle);
481 This is called during the option negotiation phase of the protocol
482 to get the size (in bytes) of the block device being exported.
484 The returned size must be E<ge> 0.  If there is an error, C<.get_size>
485 should call C<nbdkit_error> with an error message and return C<-1>.
487 =head2 C<.can_write>
489  int can_write (void *handle);
491 This is called during the option negotiation phase to find out if the
492 handle supports writes.
494 If there is an error, C<.can_write> should call C<nbdkit_error> with
495 an error message and return C<-1>.
497 This callback is not required.  If omitted, then we return true iff a
498 C<.pwrite> callback has been defined.
500 =head2 C<.can_flush>
502  int can_flush (void *handle);
504 This is called during the option negotiation phase to find out if the
505 handle supports the flush-to-disk operation.
507 If there is an error, C<.can_flush> should call C<nbdkit_error> with
508 an error message and return C<-1>.
510 This callback is not required.  If omitted, then we return true iff a
511 C<.flush> callback has been defined.
513 =head2 C<.is_rotational>
515  int is_rotational (void *handle);
517 This is called during the option negotiation phase to find out if the
518 backing disk is a rotational medium (like a traditional hard disk) or
519 not (like an SSD).  If true, this may cause the client to reorder
520 requests to make them more efficient for a slow rotating disk.
522 If there is an error, C<.is_rotational> should call C<nbdkit_error>
523 with an error message and return C<-1>.
525 This callback is not required.  If omitted, then we return false.
527 =head2 C<.can_trim>
529  int can_trim (void *handle);
531 This is called during the option negotiation phase to find out if the
532 plugin supports the trim/discard operation for punching holes in the
533 backing storage.
535 If there is an error, C<.can_trim> should call C<nbdkit_error> with an
536 error message and return C<-1>.
538 This callback is not required.  If omitted, then we return true iff a
539 C<.trim> callback has been defined.
541 =head2 C<.can_zero>
543  int can_zero (void *handle);
545 This is called during the option negotiation phase to find out if the
546 plugin wants the C<.zero> callback to be utilized.  Support for
547 writing zeroes is still advertised to the client (unless the
548 L<nbdkit-nozero-filter(1)> is also used), so returning false merely
549 serves as a way to avoid complicating the C<.zero> callback to have to
550 fail with C<ENOTSUP> or C<EOPNOTSUPP> on the connections where it will
551 never be more efficient than using C<.pwrite> up front.
553 If there is an error, C<.can_zero> should call C<nbdkit_error> with an
554 error message and return C<-1>.
556 This callback is not required.  If omitted, then for a normal zero
557 request, nbdkit always tries C<.zero> first if it is present, and
558 gracefully falls back to C<.pwrite> if C<.zero> was absent or failed
559 with C<ENOTSUP> or C<EOPNOTSUPP>.
561 =head2 C<.can_fast_zero>
563  int can_fast_zero (void *handle);
565 This is called during the option negotiation phase to find out if the
566 plugin wants to advertise support for fast zero requests.  If this
567 support is not advertised, a client cannot attempt fast zero requests,
568 and has no way to tell if writing zeroes offers any speedups compared
569 to using C<.pwrite> (other than compressed network traffic).  If
570 support is advertised, then C<.zero> will have
571 C<NBDKIT_FLAG_FAST_ZERO> set when the client has requested a fast
572 zero, in which case the plugin must fail with C<ENOTSUP> or
573 C<EOPNOTSUPP> up front if the request would not offer any benefits
574 over C<.pwrite>.  Advertising support for fast zero requests does not
575 require that writing zeroes be fast, only that the result (whether
576 success or failure) is fast, so this should be advertised when
577 feasible.
579 If there is an error, C<.can_fast_zero> should call C<nbdkit_error>
580 with an error message and return C<-1>.
582 This callback is not required.  If omitted, then nbdkit returns true
583 if C<.zero> is absent or C<.can_zero> returns false (in those cases,
584 nbdkit fails all fast zero requests, as its fallback to C<.pwrite> is
585 not inherently faster), otherwise false (since it cannot be determined
586 in advance if the plugin's C<.zero> will properly honor the semantics
587 of C<NBDKIT_FLAG_FAST_ZERO>).
589 =head2 C<.can_extents>
591  int can_extents (void *handle);
593 This is called during the option negotiation phase to find out if the
594 plugin supports detecting allocated (non-sparse) regions of the disk
595 with the C<.extents> callback.
597 If there is an error, C<.can_extents> should call C<nbdkit_error> with
598 an error message and return C<-1>.
600 This callback is not required.  If omitted, then we return true iff a
601 C<.extents> callback has been defined.
603 =head2 C<.can_fua>
605  int can_fua (void *handle);
607 This is called during the option negotiation phase to find out if the
608 plugin supports the Forced Unit Access (FUA) flag on write, zero, and
609 trim requests.  If this returns C<NBDKIT_FUA_NONE>, FUA support is not
610 advertised to the client; if this returns C<NBDKIT_FUA_EMULATE>, the
611 C<.flush> callback must work (even if C<.can_flush> returns false),
612 and FUA support is emulated by calling C<.flush> after any write
613 operation; if this returns C<NBDKIT_FUA_NATIVE>, then the C<.pwrite>,
614 C<.zero>, and C<.trim> callbacks (if implemented) must handle the flag
615 C<NBDKIT_FLAG_FUA>, by not returning until that action has landed in
616 persistent storage.
618 If there is an error, C<.can_fua> should call C<nbdkit_error> with an
619 error message and return C<-1>.
621 This callback is not required unless a plugin wants to specifically
622 handle FUA requests.  If omitted, nbdkit checks whether C<.flush>
623 exists, and behaves as if this function returns C<NBDKIT_FUA_NONE> or
624 C<NBDKIT_FUA_EMULATE> as appropriate.
626 =head2 C<.can_multi_conn>
628  int can_multi_conn (void *handle);
630 This is called during the option negotiation phase to find out if the
631 plugin is prepared to handle multiple connections from a single
632 client.  If the plugin sets this to true then a client may try to open
633 multiple connections to the nbdkit server and spread requests across
634 all connections to maximize parallelism.  If the plugin sets it to
635 false (which is the default) then well-behaved clients should only
636 open a single connection, although we cannot control what clients do
637 in practice.
639 Specifically it means that either the plugin does not cache requests
640 at all.  Or if it does cache them then the effects of a C<.flush>
641 request or setting C<NBDKIT_FLAG_FUA> on a request must be visible
642 across all connections to the plugin before the plugin replies to that
643 request.
645 Properly working clients should send the same export name for each of
646 these connections.
648 If you use Linux L<nbd-client(8)> option S<I<-C num>> with
649 S<num E<gt> 1> then Linux checks this flag and will refuse to connect
650 if C<.can_multi_conn> is false.
652 If there is an error, C<.can_multi_conn> should call C<nbdkit_error>
653 with an error message and return C<-1>.
655 This callback is not required.  If omitted, then we return false.
657 =head2 C<.can_cache>
659  int can_cache (void *handle);
661 This is called during the option negotiation phase to find out if the
662 plugin supports a cache operation. The nature of the caching is
663 unspecified (including whether there are limits on how much can be
664 cached at once, and whether writes to a cached region have
665 write-through or write-back semantics), but the command exists to let
666 clients issue a hint to the server that they will be accessing that
667 region of the export.
669 If this returns C<NBDKIT_CACHE_NONE>, cache support is not advertised
670 to the client; if this returns C<NBDKIT_CACHE_EMULATE>, caching is
671 emulated by the server calling C<.pread> and ignoring the results; if
672 this returns C<NBDKIT_CACHE_NATIVE>, then the C<.cache> callback will
673 be used.  If there is an error, C<.can_cache> should call
674 C<nbdkit_error> with an error message and return C<-1>.
676 This callback is not required.  If omitted, then we return
677 C<NBDKIT_CACHE_NONE> if the C<.cache> callback is missing, or
678 C<NBDKIT_CACHE_NATIVE> if it is defined.
680 =head2 C<.pread>
682  int pread (void *handle, void *buf, uint32_t count, uint64_t offset,
683             uint32_t flags);
685 During the data serving phase, nbdkit calls this callback to read data
686 from the backing store.  C<count> bytes starting at C<offset> in the
687 backing store should be read and copied into C<buf>.  nbdkit takes
688 care of all bounds- and sanity-checking, so the plugin does not need
689 to worry about that.
691 The parameter C<flags> exists in case of future NBD protocol
692 extensions; at this time, it will be 0 on input.
694 The callback must read the whole C<count> bytes if it can.  The NBD
695 protocol doesn't allow partial reads (instead, these would be errors).
696 If the whole C<count> bytes was read, the callback should return C<0>
697 to indicate there was I<no> error.
699 If there is an error (including a short read which couldn't be
700 recovered from), C<.pread> should call C<nbdkit_error> with an error
701 message, and C<nbdkit_set_error> to record an appropriate error
702 (unless C<errno> is sufficient), then return C<-1>.
704 =head2 C<.pwrite>
706  int pwrite (void *handle, const void *buf, uint32_t count, uint64_t offset,
707              uint32_t flags);
709 During the data serving phase, nbdkit calls this callback to write
710 data to the backing store.  C<count> bytes starting at C<offset> in
711 the backing store should be written using the data in C<buf>.  nbdkit
712 takes care of all bounds- and sanity-checking, so the plugin does not
713 need to worry about that.
715 This function will not be called if C<.can_write> returned false.  The
716 parameter C<flags> may include C<NBDKIT_FLAG_FUA> on input based on
717 the result of C<.can_fua>.
719 The callback must write the whole C<count> bytes if it can.  The NBD
720 protocol doesn't allow partial writes (instead, these would be
721 errors).  If the whole C<count> bytes was written successfully, the
722 callback should return C<0> to indicate there was I<no> error.
724 If there is an error (including a short write which couldn't be
725 recovered from), C<.pwrite> should call C<nbdkit_error> with an error
726 message, and C<nbdkit_set_error> to record an appropriate error
727 (unless C<errno> is sufficient), then return C<-1>.
729 =head2 C<.flush>
731  int flush (void *handle, uint32_t flags);
733 During the data serving phase, this callback is used to
734 L<fdatasync(2)> the backing store, ie. to ensure it has been
735 completely written to a permanent medium.  If that is not possible
736 then you can omit this callback.
738 This function will not be called directly by the client if
739 C<.can_flush> returned false; however, it may still be called by
740 nbdkit if C<.can_fua> returned C<NBDKIT_FUA_EMULATE>.  The parameter
741 C<flags> exists in case of future NBD protocol extensions; at this
742 time, it will be 0 on input.
744 If there is an error, C<.flush> should call C<nbdkit_error> with an
745 error message, and C<nbdkit_set_error> to record an appropriate error
746 (unless C<errno> is sufficient), then return C<-1>.
748 =head2 C<.trim>
750  int trim (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
752 During the data serving phase, this callback is used to "punch holes"
753 in the backing store.  If that is not possible then you can omit this
754 callback.
756 This function will not be called if C<.can_trim> returned false.  The
757 parameter C<flags> may include C<NBDKIT_FLAG_FUA> on input based on
758 the result of C<.can_fua>.
760 If there is an error, C<.trim> should call C<nbdkit_error> with an
761 error message, and C<nbdkit_set_error> to record an appropriate error
762 (unless C<errno> is sufficient), then return C<-1>.
764 =head2 C<.zero>
766  int zero (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
768 During the data serving phase, this callback is used to write C<count>
769 bytes of zeroes at C<offset> in the backing store.
771 This function will not be called if C<.can_zero> returned false.  On
772 input, the parameter C<flags> may include C<NBDKIT_FLAG_MAY_TRIM>
773 unconditionally, C<NBDKIT_FLAG_FUA> based on the result of
774 C<.can_fua>, and C<NBDKIT_FLAG_FAST_ZERO> based on the result of
775 C<.can_fast_zero>.
777 If C<NBDKIT_FLAG_MAY_TRIM> is requested, the operation can punch a
778 hole instead of writing actual zero bytes, but only if subsequent
779 reads from the hole read as zeroes.
781 If C<NBDKIT_FLAG_FAST_ZERO> is requested, the plugin must decide up
782 front if the implementation is likely to be faster than a
783 corresponding C<.pwrite>; if not, then it must immediately fail with
784 C<ENOTSUP> or C<EOPNOTSUPP> (whether by C<nbdkit_set_error> or
785 C<errno>) and preferably without modifying the exported image.  It is
786 acceptable to always fail a fast zero request (as a fast failure is
787 better than attempting the write only to find out after the fact that
788 it was not fast after all).  Note that on Linux, support for
789 C<ioctl(BLKZEROOUT)> is insufficient for determining whether a zero
790 request to a block device will be fast (because the kernel will
791 perform a slow fallback when needed).
793 The callback must write the whole C<count> bytes if it can.  The NBD
794 protocol doesn't allow partial writes (instead, these would be
795 errors).  If the whole C<count> bytes was written successfully, the
796 callback should return C<0> to indicate there was I<no> error.
798 If there is an error, C<.zero> should call C<nbdkit_error> with an
799 error message, and C<nbdkit_set_error> to record an appropriate error
800 (unless C<errno> is sufficient), then return C<-1>.
802 If this callback is omitted, or if it fails with C<ENOTSUP> or
803 C<EOPNOTSUPP> (whether by C<nbdkit_set_error> or C<errno>), then
804 C<.pwrite> will be used as an automatic fallback except when the
805 client requested a fast zero.
807 =head2 C<.extents>
809  int extents (void *handle, uint32_t count, uint64_t offset,
810               uint32_t flags, struct nbdkit_extents *extents);
812 During the data serving phase, this callback is used to detect
813 allocated, sparse and zeroed regions of the disk.
815 This function will not be called if C<.can_extents> returned false.
816 nbdkit's default behaviour in this case is to treat the whole virtual
817 disk as if it was allocated.  Also, this function will not be called
818 by a client that does not request structured replies (the I<--no-sr>
819 option of nbdkit can be used to test behavior when C<.extents> is
820 unavailable to the client).
822 The callback should detect and return the list of extents overlapping
823 the range C<[offset...offset+count-1]>.  The C<extents> parameter
824 points to an opaque object which the callback should fill in by
825 calling C<nbdkit_add_extent>.  See L</Extents list> below.
827 If there is an error, C<.extents> should call C<nbdkit_error> with an
828 error message, and C<nbdkit_set_error> to record an appropriate error
829 (unless C<errno> is sufficient), then return C<-1>.
831 =head3 Extents list
833 The plugin C<extents> callback is passed an opaque pointer C<struct
834 nbdkit_extents *extents>.  This structure represents a list of
835 L<filesystem extents|https://en.wikipedia.org/wiki/Extent_(file_systems)>
836 describing which areas of the disk are allocated, which are sparse
837 (“holes”), and, if supported, which are zeroes.
839 The C<extents> callback should scan the disk starting at C<offset> and
840 call C<nbdkit_add_extent> for each extent found.
842 Extents overlapping the range C<[offset...offset+count-1]> should be
843 returned if possible.  However nbdkit ignores extents E<lt> offset so
844 the plugin may, if it is easier to implement, return all extent
845 information for the whole disk.  The plugin may return extents beyond
846 the end of the range.  It may also return extent information for less
847 than the whole range, but it must return at least one extent
848 overlapping C<offset>.
850 The extents B<must> be added in ascending order, and B<must> be
851 contiguous.
853 The C<flags> parameter of the C<.extents> callback may contain the
854 flag C<NBDKIT_FLAG_REQ_ONE>.  This means that the client is only
855 requesting information about the extent overlapping C<offset>.  The
856 plugin may ignore this flag, or as an optimization it may return just
857 a single extent for C<offset>.
859  int nbdkit_add_extent (struct nbdkit_extents *extents,
860                         uint64_t offset, uint64_t length, uint32_t type);
862 Add an extent covering C<[offset...offset+length-1]> of one of
863 the following four types:
865 =over 4
867 =item C<type = 0>
869 A normal, allocated data extent.
871 =item C<type = NBDKIT_EXTENT_HOLE|NBDKIT_EXTENT_ZERO>
873 An unallocated extent, a.k.a. a “hole”, which reads back as zeroes.
874 This is the normal type of hole applicable to most disks.
876 =item C<type = NBDKIT_EXTENT_ZERO>
878 An allocated extent which is known to contain only zeroes.
880 =item C<type = NBDKIT_EXTENT_HOLE>
882 An unallocated extent (hole) which does not read back as zeroes.  Note
883 this should only be used in specialized circumstances such as when
884 writing a plugin for (or to emulate) certain SCSI drives which do not
885 guarantee that trimmed blocks read back as zeroes.
887 =back
889 C<nbdkit_extent_add> returns C<0> on success or C<-1> on failure.  On
890 failure C<nbdkit_error> and/or C<nbdkit_set_error> has already been
891 called.  C<errno> will be set to a suitable value.
893 =head2 C<.cache>
895  int cache (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
897 During the data serving phase, this callback is used to give the
898 plugin a hint that the client intends to make further accesses to the
899 given region of the export.  The nature of caching is not specified
900 further by the NBD specification (for example, a server may place
901 limits on how much may be cached at once, and there is no way to
902 control if writes to a cached area have write-through or write-back
903 semantics).  In fact, the cache command can always fail and still be
904 compliant, and success might not guarantee a performance gain.  If
905 this callback is omitted, then the results of C<.can_cache> determine
906 whether nbdkit will reject cache requests, treat them as instant
907 success, or emulate caching by calling C<.pread> over the same region
908 and ignoring the results.
910 This function will not be called if C<.can_cache> did not return
911 C<NBDKIT_CACHE_NATIVE>.  The parameter C<flags> exists in case of
912 future NBD protocol extensions; at this time, it will be 0 on input. A
913 plugin must fail this function if C<flags> includes an unrecognized
914 flag, as that may indicate a requirement that the plugin comply must
915 with a specific caching semantic.
917 If there is an error, C<.cache> should call C<nbdkit_error> with an
918 error message, and C<nbdkit_set_error> to record an appropriate error
919 (unless C<errno> is sufficient), then return C<-1>.
921 =head1 OTHER FIELDS
923 The plugin struct also contains an integer field used as a
924 boolean in C code, but unlikely to be exposed in other language
925 bindings:
927 =over 4
929 =item C<.errno_is_preserved>
931 This defaults to 0; if non-zero, nbdkit can reliably use the value of
932 C<errno> when a callback reports failure, rather than the plugin
933 having to call C<nbdkit_set_error>.
935 =back
937 =head1 THREADS
939 Each nbdkit plugin must declare its maximum thread safety model by
940 defining the C<THREAD_MODEL> macro.  (This macro is used by
941 C<NBDKIT_REGISTER_PLUGIN>).  Additionally, a plugin may implement the
942 C<.thread_model> callback, called right after C<.config_complete> to
943 make a runtime decision on which thread model to use.  The nbdkit
944 server chooses the most restrictive model between the plugin's
945 C<THREAD_MODEL>, the C<.thread_model> if present, any restrictions
946 requested by filters, and any limitations imposed by the system (for
947 example, a system without atomic C<FD_CLOEXEC> will serialize all
948 requests, so as to avoid nbdkit leaking a new file descriptor from one
949 thread into a child process created by another thread).
951 In C<nbdkit --dump-plugin PLUGIN> output, the C<max_thread_model> line
952 matches the C<THREAD_MODEL> macro, and the C<thread_model> line
953 matches what the system finally settled on after applying all
954 restrictions.
956 The possible settings for C<THREAD_MODEL> are defined below.
958 =over 4
960 =item C<#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_CONNECTIONS>
962 Only a single handle can be open at any time, and all requests happen
963 from one thread.
965 Note this means only one client can connect to the server at any time.
966 If a second client tries to connect it will block waiting for the
967 first client to close the connection.
969 =item C<#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS>
971 I<This is a safe default for most plugins>.
973 Multiple handles can be open at the same time, but requests are
974 serialized so that for the plugin as a whole only one
975 open/read/write/close (etc) request will be in progress at any time.
977 This is a useful setting if the library you are using is not
978 thread-safe.  However performance may not be good.
980 =item C<#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_REQUESTS>
982 Multiple handles can be open and multiple data requests can happen in
983 parallel.  However only one request will happen per handle at a time
984 (but requests on different handles might happen concurrently).
986 =item C<#define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL>
988 Multiple handles can be open and multiple data requests can happen in
989 parallel (even on the same handle).  The server may reorder replies,
990 answering a later request before an earlier one.
992 All the libraries you use must be thread-safe and reentrant, and any
993 code that creates a file descriptor should atomically set
994 C<FD_CLOEXEC> if you do not want it accidentally leaked to another
995 thread's child process.  You may also need to provide mutexes for
996 fields in your connection handle.
998 =back
1000 If none of the above thread models are suitable, then use
1001 C<NBDKIT_THREAD_MODEL_PARALLEL> and implement your own locking using
1002 C<pthread_mutex_t> etc.
1004 =head1 SHUTDOWN
1006 When nbdkit receives certain signals it will shut down (see
1007 L<nbdkit(1)/SIGNALS>).  The server will wait for any currently running
1008 plugin callbacks to finish and also call the C<.unload> callback
1009 before unloading the plugin.
1011 Note that it's not guaranteed this can always happen (eg. the server
1012 might be killed by C<SIGKILL> or segfault).
1014 =head1 PARSING COMMAND LINE PARAMETERS
1016 =head2 Parsing numbers
1018 There are several functions for parsing numbers.  These all deal
1019 correctly with overflow, out of range and parse errors, and you should
1020 use them instead of unsafe functions like L<sscanf(3)>, L<atoi(3)> and
1021 similar.
1023  int nbdkit_parse_int (const char *what, const char *str, int *r);
1024  int nbdkit_parse_unsigned (const char *what,
1025                             const char *str, unsigned *r);
1026  int nbdkit_parse_int8_t (const char *what,
1027                           const char *str, int8_t *r);
1028  int nbdkit_parse_uint8_t (const char *what,
1029                            const char *str, uint8_t *r);
1030  int nbdkit_parse_int16_t (const char *what,
1031                            const char *str, int16_t *r);
1032  int nbdkit_parse_uint16_t (const char *what,
1033                             const char *str, uint16_t *r);
1034  int nbdkit_parse_int32_t (const char *what,
1035                            const char *str, int32_t *r);
1036  int nbdkit_parse_uint32_t (const char *what,
1037                             const char *str, uint32_t *r);
1038  int nbdkit_parse_int64_t (const char *what,
1039                            const char *str, int64_t *r);
1040  int nbdkit_parse_uint64_t (const char *what,
1041                             const char *str, uint64_t *r);
1043 Parse string C<str> into an integer of various types.  These functions
1044 parse a decimal, hexadecimal (C<"0x...">) or octal (C<"0...">) number.
1046 On success the functions return C<0> and set C<*r> to the parsed value
1047 (unless C<*r == NULL> in which case the result is discarded).  On
1048 error, C<nbdkit_error> is called and the functions return C<-1>.  On
1049 error C<*r> is always unchanged.
1051 The C<what> parameter is printed in error messages to provide context.
1052 It should usually be a short descriptive string of what you are trying
1053 to parse, eg:
1055  if (nbdkit_parse_int ("random seed", argv[1], &seed) == -1)
1056    return -1;
1058 might print an error:
1060  random seed: could not parse number: "lalala"
1062 =head2 Parsing sizes
1064 Use the C<nbdkit_parse_size> utility function to parse human-readable
1065 size strings such as "100M" into the size in bytes.
1067  int64_t nbdkit_parse_size (const char *str);
1069 C<str> can be a string in a number of common formats.  The function
1070 returns the size in bytes.  If there was an error, it returns C<-1>.
1072 =head2 Parsing booleans
1074 Use the C<nbdkit_parse_bool> utility function to parse human-readable
1075 strings such as "on" into a boolean value.
1077  int nbdkit_parse_bool (const char *str);
1079 C<str> can be a string containing a case-insensitive form of various
1080 common toggle values.  The function returns 0 or 1 if the parse was
1081 successful.  If there was an error, it returns C<-1>.
1083 =head2 Reading passwords
1085 The C<nbdkit_read_password> utility function can be used to read
1086 passwords from config parameters:
1088  int nbdkit_read_password (const char *value, char **password);
1090 For example:
1092  char *password = NULL;
1094  static int
1095  myplugin_config (const char *key, const char *value)
1097    ..
1098    if (strcmp (key, "password") == 0) {
1099      free (password);
1100      if (nbdkit_read_password (value, &password) == -1)
1101        return -1;
1102    }
1103    ..
1106 The C<password> result string is allocated by malloc, and so you may
1107 need to free it.
1109 This function recognizes several password formats.  A password may be
1110 used directly on the command line, eg:
1112  nbdkit myplugin password=mostsecret
1114 But more securely this function can also read a password
1115 interactively:
1117  nbdkit myplugin password=-
1119 or from a file:
1121  nbdkit myplugin password=+/tmp/secret
1123 or from a file descriptor inherited by nbdkit:
1125  nbdkit myplugin password=-99
1127 (If the password begins with a C<-> or C<+> character then it must be
1128 passed in a file).
1130 =head1 FILENAMES AND PATHS
1132 The server usually (not always) changes directory to C</> before it
1133 starts serving connections.  This means that any relative paths passed
1134 during configuration will not work when the server is running
1135 (example: S<C<nbdkit plugin.so disk.img>>).
1137 To avoid problems, prepend relative paths with the current directory
1138 before storing them in the handle.  Or open files and store the file
1139 descriptor.
1141 =head2 C<nbdkit_absolute_path>
1143  char *nbdkit_absolute_path (const char *filename);
1145 The utility function C<nbdkit_absolute_path> converts any path to an
1146 absolute path: if it is relative, then all this function does is
1147 prepend the current working directory to the path, with no extra
1148 checks.
1150 Note that this function works I<only> when used in the C<.config>, and
1151 C<.config_complete> callbacks.
1153 If conversion was not possible, this calls C<nbdkit_error> and returns
1154 C<NULL>.  Note that this function does not check that the file exists.
1156 The returned string must be freed by the caller.
1158 =head2 C<nbdkit_realpath>
1160  char *nbdkit_realpath (const char *filename);
1162 The utility function C<nbdkit_realpath> converts any path to an
1163 absolute path, resolving symlinks.  Under the hood it uses the
1164 C<realpath> function, and thus it fails if the path does not exist,
1165 or it is not possible to access to any of the components of the path.
1167 Note that this function works I<only> when used in the C<.config>, and
1168 C<.config_complete> callbacks.
1170 If the path resolution was not possible, this calls C<nbdkit_error>
1171 and returns C<NULL>.
1173 The returned string must be freed by the caller.
1175 =head2 umask
1177 All plugins will see a L<umask(2)> of C<0022>.
1179 =head1 SLEEPING
1181 A plugin that needs to sleep may call L<sleep(2)>, L<nanosleep(2)> and
1182 similar.  However that can cause nbdkit to delay excessively when
1183 shutting down (since it must wait for any plugin or filter which is
1184 sleeping).  To avoid this there is a special wrapper around nanosleep
1185 which plugins and filters should use instead.
1187 =head2 C<nbdkit_nanosleep>
1189  int nbdkit_nanosleep (unsigned sec, unsigned nsec);
1191 The utility function C<nbdkit_nanosleep> suspends the current thread,
1192 and returns 0 if it slept at least as many seconds and nanoseconds as
1193 requested, or -1 after calling C<nbdkit_error> if there is no point in
1194 continuing the current command.  Attempts to sleep more than
1195 C<INT_MAX> seconds are treated as an error.
1197 =head1 EXPORT NAME
1199 If the client negotiated an NBD export name with nbdkit then plugins
1200 may read this from any connected callbacks.  Nbdkit's normal behaviour
1201 is to accept any export name passed by the client, log it in debug
1202 output, but otherwise ignore it.  By using C<nbdkit_export_name>
1203 plugins may choose to filter by export name or serve different
1204 content.
1206 =head2 C<nbdkit_export_name>
1208  const char *nbdkit_export_name (void);
1210 Return the optional NBD export name if one was negotiated with the
1211 current client (this uses thread-local magic so no parameter is
1212 required).  The returned string is only valid while the client is
1213 connected, so if you need to store it in the plugin you must copy it.
1215 The export name is a free-form text string, it is not necessarily a
1216 path or filename and it does not need to begin with a C<'/'>
1217 character.  The NBD protocol describes the empty string (C<"">) as a
1218 representing a "default export" or to be used in cases where the
1219 export name does not make sense.  B<The export name is untrusted
1220 client data, be cautious when parsing it.>
1222 On error, C<nbdkit_error> is called and the call returns C<NULL>.
1224 =head1 PEER NAME
1226 It is possible to get the address of the client when you are running
1227 in any connected callback.
1229 =head2 C<nbdkit_peer_name>
1231  int nbdkit_peer_name (struct sockaddr *addr, socklen_t *addrlen);
1233 Return the peer (client) address, if available.  The C<addr> and
1234 C<addrlen> parameters behave like L<getpeername(2)>.  In particular
1235 you must initialize C<addrlen> with the size of the buffer pointed to
1236 by C<addr>, and if C<addr> is not large enough then the address will
1237 be truncated.
1239 In some cases this is not available or the address returned will be
1240 meaningless (eg. if there is a proxy between the client and nbdkit).
1241 This call uses thread-local magic so no parameter is required to
1242 specify the current connection.
1244 On success this returns C<0>.  On error, C<nbdkit_error> is called and
1245 this call returns C<-1>.
1247 =head1 DEBUGGING
1249 Run the server with I<-f> and I<-v> options so it doesn't fork and you
1250 can see debugging information:
1252  nbdkit -fv ./myplugin.so [key=value [key=value [...]]]
1254 To print debugging information from within the plugin, call
1255 C<nbdkit_debug>, which has the following prototype and works like
1256 L<printf(3)>:
1258  void nbdkit_debug (const char *fs, ...);
1259  void nbdkit_vdebug (const char *fs, va_list args);
1261 For convenience, C<nbdkit_debug> preserves the value of C<errno>, and
1262 also supports the glibc extension of a single C<%m> in a format string
1263 expanding to C<strerror(errno)>, even on platforms that don't support
1264 that natively. Note that C<nbdkit_debug> only prints things when the
1265 server is in verbose mode (I<-v> option).
1267 =head2 Debug Flags
1269 The I<-v> option switches general debugging on or off, and this
1270 debugging should be used for messages which are useful for all users
1271 of your plugin.
1273 In cases where you want to enable specific extra debugging to track
1274 down bugs in plugins or filters — mainly for use by the plugin/filter
1275 developers themselves — you can define Debug Flags.  These are global
1276 ints called C<myplugin_debug_*>:
1278  int myplugin_debug_foo;
1279  int myplugin_debug_bar;
1280  ...
1281  if (myplugin_debug_foo) {
1282    nbdkit_debug ("lots of extra debugging about foo: ...");
1285 Debug Flags can be controlled on the command line using the I<-D> (or
1286 I<--debug>) option:
1288  nbdkit -f -v -D myplugin.foo=1 -D myplugin.bar=2 myplugin [...]
1290 Note C<myplugin> is the name passed to C<.name> in the C<struct
1291 nbdkit_plugin>.
1293 You should only use this feature for debug settings.  For general
1294 settings use ordinary plugin parameters.  Debug Flags can only be C
1295 ints.  They are not supported by non-C language plugins.
1297 =head1 INSTALLING THE PLUGIN
1299 The plugin is a C<*.so> file and possibly a manual page.  You can of
1300 course install the plugin C<*.so> file wherever you want, and users
1301 will be able to use it by running:
1303  nbdkit /path/to/plugin.so [args]
1305 However B<if> the shared library has a name of the form
1306 C<nbdkit-I<name>-plugin.so> B<and if> the library is installed in the
1307 C<$plugindir> directory, then users can be run it by only typing:
1309  nbdkit name [args]
1311 The location of the C<$plugindir> directory is set when nbdkit is
1312 compiled and can be found by doing:
1314  nbdkit --dump-config
1316 If using the pkg-config/pkgconf system then you can also find the
1317 plugin directory at compile time by doing:
1319  pkgconf nbdkit --variable=plugindir
1321 =head1 PKG-CONFIG/PKGCONF
1323 nbdkit provides a pkg-config/pkgconf file called C<nbdkit.pc> which
1324 should be installed on the correct path when the nbdkit plugin
1325 development environment is installed.  You can use this in autoconf
1326 F<configure.ac> scripts to test for the development environment:
1328  PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])
1330 The above will fail unless nbdkit E<ge> 1.2.3 and the header file is
1331 installed, and will set C<NBDKIT_CFLAGS> and C<NBDKIT_LIBS>
1332 appropriately for compiling plugins.
1334 You can also run pkg-config/pkgconf directly, for example:
1336  if ! pkgconf nbdkit --exists; then
1337    echo "you must install the nbdkit plugin development environment"
1338    exit 1
1339  fi
1341 You can also substitute the plugindir variable by doing:
1343  PKG_CHECK_VAR([NBDKIT_PLUGINDIR], [nbdkit], [plugindir])
1345 which defines C<$(NBDKIT_PLUGINDIR)> in automake-generated Makefiles.
1347 =head1 WRITING PLUGINS IN OTHER PROGRAMMING LANGUAGES
1349 You can also write nbdkit plugins in Lua, OCaml, Perl, Python, Ruby,
1350 Rust, shell script or Tcl.  Other programming languages may be offered
1351 in future.
1353 For more information see:
1354 __LANG_PLUGIN_LINKS__.
1356 Plugins written in scripting languages may also be installed in
1357 C<$plugindir>.  These must be called C<nbdkit-I<name>-plugin> without
1358 any extension.  They must be executable, and they must use the shebang
1359 header (see L<nbdkit(1)/Shebang scripts>).  For example a plugin
1360 written in Perl called C<foo.pl> might be installed like this:
1362  $ head -1 foo.pl
1363  #!/usr/sbin/nbdkit perl
1365  $ sudo install -m 0755 foo.pl $plugindir/nbdkit-foo-plugin
1367 and then users will be able to run it like this:
1369  $ nbdkit foo [args ...]
1371 =head1 SEE ALSO
1373 L<nbdkit(1)>,
1374 L<nbdkit-nozero-filter(3)>,
1375 L<nbdkit-filter(3)>.
1377 Standard plugins provided by nbdkit:
1379 __PLUGIN_LINKS__.
1381 =head1 AUTHORS
1383 Eric Blake
1385 Richard W.M. Jones
1387 Pino Toscano
1389 =head1 COPYRIGHT
1391 Copyright (C) 2013-2018 Red Hat Inc.