1nbdkit-plugin(3)                    NBDKIT                    nbdkit-plugin(3)
2
3
4

NAME

6       nbdkit-plugin - how to write nbdkit plugins
7

SYNOPSIS

9        #define NBDKIT_API_VERSION 2
10        #include <nbdkit-plugin.h>
11
12        #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
13
14        static void *
15        myplugin_open (void)
16        {
17          /* create a handle ... */
18          return handle;
19        }
20
21        static struct nbdkit_plugin plugin = {
22          .name              = "myplugin",
23          .open              = myplugin_open,
24          .get_size          = myplugin_get_size,
25          .pread             = myplugin_pread,
26          .pwrite            = myplugin_pwrite,
27          /* etc */
28        };
29        NBDKIT_REGISTER_PLUGIN(plugin)
30
31       Compile the plugin as a shared library:
32
33        gcc -fPIC -shared myplugin.c -o myplugin.so
34
35       and load it into nbdkit:
36
37        nbdkit [--args ...] ./myplugin.so [key=value ...]
38
39       When debugging, use the -fv options:
40
41        nbdkit -fv ./myplugin.so [key=value ...]
42

DESCRIPTION

44       An nbdkit plugin is a new source device which can be served using the
45       Network Block Device (NBD) protocol.  This manual page describes how to
46       create an nbdkit plugin in C.
47
48       To see example plugins:
49       https://gitlab.com/nbdkit/nbdkit/tree/master/plugins
50
51       To write plugins in other languages, see: nbdkit-cc-plugin(3),
52       nbdkit-golang-plugin(3), nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3),
53       nbdkit-perl-plugin(3), nbdkit-python-plugin(3), nbdkit-ruby-plugin(3),
54       nbdkit-rust-plugin(3), nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .
55
56   API and ABI guarantee for C plugins
57       Plugins written in C have an ABI guarantee: a plugin compiled against
58       an older version of nbdkit will still work correctly when loaded with a
59       newer nbdkit.  We also try (but cannot guarantee) to support plugins
60       compiled against a newer version of nbdkit when loaded with an older
61       nbdkit, although the plugin may have reduced functionality if it
62       depends on features only provided by newer nbdkit.
63
64       For plugins written in C, we also provide an API guarantee: a plugin
65       written against an older header will still compile unmodified with a
66       newer nbdkit.
67
68       The API guarantee does not always apply to plugins written in other
69       (non-C) languages which may have to adapt to changes when recompiled
70       against a newer nbdkit.
71

WRITING AN NBDKIT PLUGIN

73   "#define NBDKIT_API_VERSION 2"
74       Plugins must choose which API version they want to use, by defining
75       NBDKIT_API_VERSION before including "<nbdkit-plugin.h>" (or any other
76       nbdkit header).
77
78       If omitted, the default version is 1 for backwards-compatibility with
79       nbdkit v1.1.26 and earlier; however, it is recommended that new plugins
80       be written to the maximum version (currently 2) as it enables more
81       features and better interaction with nbdkit filters.
82
83       The rest of this document only covers the version 2 interface.  A newer
84       nbdkit will always support plugins written in C which use any prior API
85       version.
86
87   "#include <nbdkit-plugin.h>"
88       All plugins should start by including this header file (after
89       optionally choosing an API version).
90
91   "#define THREAD_MODEL ..."
92       All plugins must define a thread model.  See "Threads" below for
93       details.  It is generally safe to use:
94
95        #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
96
97   "struct nbdkit_plugin"
98       All plugins must define and register one "struct nbdkit_plugin", which
99       contains the name of the plugin and pointers to callback functions, and
100       use the NBDKIT_REGISTER_PLUGIN(plugin) macro:
101
102        static struct nbdkit_plugin plugin = {
103          .name              = "myplugin",
104          .longname          = "My Plugin",
105          .description       = "This is my great plugin for nbdkit",
106          .open              = myplugin_open,
107          .get_size          = myplugin_get_size,
108          .pread             = myplugin_pread,
109          .pwrite            = myplugin_pwrite,
110          /* etc */
111        };
112        NBDKIT_REGISTER_PLUGIN(plugin)
113
114       The ".name" field is the name of the plugin.
115
116       The callbacks are described below (see "CALLBACKS").  Only ".name",
117       ".open", ".get_size" and ".pread" are required.  All other callbacks
118       can be omitted, although typical plugins need to use more.
119
120   Callback lifecycle
121       Callbacks are called in the following order over the lifecycle of the
122       plugin:
123
124                ┌──────────────────┐
125                │ load             │
126                └─────────┬────────┘
127                          │           configuration phase starts     ─┐
128                ┌─────────┴────────┐                                  ┆
129                │ config           │  config is called once per       ┆
130                └─────────┬────────┘↺ key=value on the command line   ┆
131                ┌─────────┴────────┐                                  ┆
132                │ config_complete  │                                  ┆
133                └─────────┬────────┘                                  ┆
134                ┌─────────┴────────┐                                  ┆
135                │ thread_model     │                                  ┆
136                └─────────┬────────┘  configuration phase ends       ─┘
137                ┌─────────┴────────┐
138                │ get_ready        │
139                └─────────┬────────┘
140                          │           nbdkit forks into the background
141                ┌─────────┴────────┐
142                │ after_fork       │
143                └─────────┬────────┘
144                          │           nbdkit starts serving clients
145
146               ┌──────────┴─────────────┬─ ─ ─ ─ ─ ─ ─ ─ ─
147        ┌──────┴─────┐ client #1        │
148        │ preconnect │                  │
149        └──────┬─────┘                  │
150        ┌──────┴─────┐                  │
151        │list_exports│                  │
152        └──────┬─────┘                  │
153        ┌──────┴─────┐                  │
154        │ open       │                  │
155        └──────┬─────┘                  │
156        ┌──────┴─────┐  NBD option      │
157        │ can_write  │  negotiation     │
158        └──────┬─────┘                  │
159        ┌──────┴─────┐           ┌──────┴─────┐ client #2
160        │ get_size   │           │ preconnect │
161        └──────┬─────┘           └──────┬─────┘
162        ┌──────┴─────┐ data
163        │ pread      │ serving
164        └──────┬─────┘↺                ...
165        ┌──────┴─────┐
166        │ pwrite     │
167        └──────┬─────┘↺          ┌──────┴─────┐
168        ┌──────┴─────┐           │ close      │
169        │ close      │           └────────────┘
170        └────────────┘
171
172                          │           before nbdkit exits
173
174                ┌─────────┴────────┐
175                │ cleanup          │
176                └─────────┬────────┘
177                ┌─────────┴────────┐
178                │ unload           │
179                └──────────────────┘
180
181       Notes
182
183       "nbdkit --dump-plugin"
184           The order of calls when the user queries the plugin is slightly
185           different: ".config" is called once for each parameter.
186           ".config_complete" is not called.  ".thread_model" is called after
187           ".config".
188
189       ".get_ready"
190           This is the last chance to do any global preparation that is needed
191           to serve connections.  In particular, error messages here will be
192           visible to the user, but they might not be in ".after_fork" (see
193           below).
194
195           Plugins should not create background threads here.  Use
196           ".after_fork" instead.
197
198       ".after_fork"
199           ".after_fork" is called after the server has forked into the
200           background and changed UID and directory.  If a plugin needs to
201           create background threads (or uses an external library that creates
202           threads) it should do so here, because background threads are
203           invalidated by fork.
204
205           Because the server may have forked into the background, error
206           messages and failures from ".after_fork" cannot be seen by the user
207           unless they look through syslog.  An error in ".after_fork" can
208           appear to the user as if nbdkit “just died”.  So in almost all
209           cases it is better to use ".get_ready" instead of this callback, or
210           to do as much preparation work as possible in ".get_ready" and only
211           start background threads here.
212
213           The server doesn't always fork (eg. if the -f flag is used), but
214           even so this callback will be called.  If you want to find out if
215           the server forked between ".get_ready" and ".after_fork" use
216           getpid(2).
217
218       ".preconnect" and ".open"
219           ".preconnect" is called when a TCP connection has been made to the
220           server.  This happens early, before NBD or TLS negotiation.
221
222           ".open" is called when a new client has connected and finished the
223           NBD handshake.  TLS negotiation (if used) has been completed
224           successfully.
225
226       ".can_write", ".get_size" and other option negotiation callbacks
227           These are called during option negotiation with the client, but
228           before any data is served.  These callbacks may return different
229           values across different ".open" calls, but within a single
230           connection, they are called at most once and cached by nbdkit for
231           that connection.
232
233       ".pread", ".pwrite" and other data serving callbacks
234           After option negotiation has finished, these may be called to serve
235           data.  Depending on the thread model chosen, they might be called
236           in parallel from multiple threads.  The data serving callbacks
237           include a flags argument; the results of the negotiation callbacks
238           influence whether particular flags will ever be passed to a data
239           callback.
240
241       ".cleanup" and ".unload"
242           The difference between these two methods is that ".cleanup" is
243           called before any filter has been removed from memory with
244           dlclose(3).  When ".unload" is called, nbdkit is in the middle of
245           calling dlclose(3).  Most plugins do not need to worry about this
246           difference.
247
248   Flags
249       The following flags are defined by nbdkit, and used in various data
250       serving callbacks as follows:
251
252       "NBDKIT_FLAG_MAY_TRIM"
253           This flag is used by the ".zero" callback; there is no way to
254           disable this flag, although a plugin that does not support trims as
255           a way to write zeroes may ignore the flag without violating
256           expected semantics.
257
258       "NBDKIT_FLAG_FUA"
259           This flag represents Forced Unit Access semantics.  It is used by
260           the ".pwrite", ".zero", and ".trim" callbacks to indicate that the
261           plugin must not return a result until the action has landed in
262           persistent storage.  This flag will not be sent to the plugin
263           unless ".can_fua" is provided and returns "NBDKIT_FUA_NATIVE".
264
265       The following defines are valid as successful return values for
266       ".can_fua":
267
268       "NBDKIT_FUA_NONE"
269           Forced Unit Access is not supported; the client must manually
270           request a flush after writes have completed.  The "NBDKIT_FLAG_FUA"
271           flag will not be passed to the plugin's write callbacks.
272
273       "NBDKIT_FUA_EMULATE"
274           The client may request Forced Unit Access, but it is implemented by
275           emulation, where nbdkit calls ".flush" after a write operation;
276           this is semantically correct, but may hurt performance as it tends
277           to flush more data than just what the client requested.  The
278           "NBDKIT_FLAG_FUA" flag will not be passed to the plugin's write
279           callbacks.
280
281       "NBDKIT_FUA_NATIVE"
282           The client may request Forced Unit Access, which results in the
283           "NBDKIT_FLAG_FUA" flag being passed to the plugin's write callbacks
284           (".pwrite", ".trim", and ".zero").  When the flag is set, these
285           callbacks must not return success until the client's request has
286           landed in persistent storage.
287
288       The following defines are valid as successful return values for
289       ".can_cache":
290
291       "NBDKIT_CACHE_NONE"
292           The server does not advertise caching support, and rejects any
293           client-requested caching. Any ".cache" callback is ignored.
294
295       "NBDKIT_CACHE_EMULATE"
296           The nbdkit server advertises cache support to the client, where the
297           client may request that the server cache a region of the export to
298           potentially speed up future read and/or write operations on that
299           region. The nbdkit server implements the caching by calling
300           ".pread" and ignoring the results. This option exists to ease the
301           implementation of a common form of caching; any ".cache" callback
302           is ignored.
303
304       "NBDKIT_CACHE_NATIVE"
305           The nbdkit server advertises cache support to the client, where the
306           client may request that the server cache a region of the export to
307           potentially speed up future read and/or write operations on that
308           region. The nbdkit server calls the ".cache" callback to perform
309           the caching; if that callback is missing, the client's cache
310           request succeeds without doing anything.
311
312   Threads
313       Each nbdkit plugin must declare its maximum thread safety model by
314       defining the "THREAD_MODEL" macro.  (This macro is used by
315       "NBDKIT_REGISTER_PLUGIN").  Additionally, a plugin may implement the
316       ".thread_model" callback, called right after ".config_complete" to make
317       a runtime decision on which thread model to use.  The nbdkit server
318       chooses the most restrictive model between the plugin's "THREAD_MODEL",
319       the ".thread_model" if present, any restrictions requested by filters,
320       and any limitations imposed by the operating system.
321
322       In "nbdkit --dump-plugin PLUGIN" output, the "max_thread_model" line
323       matches the "THREAD_MODEL" macro, and the "thread_model" line matches
324       what the system finally settled on after applying all restrictions.
325
326       The possible settings for "THREAD_MODEL" are defined below.
327
328       "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_CONNECTIONS"
329           Only a single handle can be open at any time, and all requests
330           happen from one thread.
331
332           Note this means only one client can connect to the server at any
333           time.  If a second client tries to connect it will block waiting
334           for the first client to close the connection.
335
336       "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS"
337           This is a safe default for most plugins.
338
339           Multiple handles can be open at the same time, but requests are
340           serialized so that for the plugin as a whole only one
341           open/read/write/close (etc) request will be in progress at any
342           time.
343
344           This is a useful setting if the library you are using is not
345           thread-safe.  However performance may not be good.
346
347       "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_REQUESTS"
348           Multiple handles can be open and multiple data requests can happen
349           in parallel.  However only one request will happen per handle at a
350           time (but requests on different handles might happen concurrently).
351
352       "#define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL"
353           Multiple handles can be open and multiple data requests can happen
354           in parallel (even on the same handle).  The server may reorder
355           replies, answering a later request before an earlier one.
356
357           All the libraries you use must be thread-safe and reentrant, and
358           any code that creates a file descriptor should atomically set
359           "FD_CLOEXEC" if you do not want it accidentally leaked to another
360           thread's child process.  You may also need to provide mutexes for
361           fields in your connection handle.
362
363       If none of the above thread models are suitable, use
364       "NBDKIT_THREAD_MODEL_PARALLEL" and implement your own locking using
365       "pthread_mutex_t" etc.
366
367   Error handling
368       If there is an error in the plugin, the plugin should call
369       "nbdkit_error" to report an error message; additionally, if the
370       callback is involved in serving data, the plugin should call
371       "nbdkit_set_error" to influence the error code that will be sent to the
372       client.  These two functions can be called in either order.  Then, the
373       callback should return the appropriate error indication, eg. "NULL" or
374       -1.
375
376       If the call to "nbdkit_set_error" is omitted while serving data, then
377       the global variable "errno" may be used.  For plugins which have
378       ".errno_is_preserved != 0" the core code will use "errno".  In plugins
379       written in non-C languages, we usually cannot trust that "errno" will
380       not be overwritten when returning from that language to C.  In that
381       case, either the plugin must call "nbdkit_set_error" or hard-coded
382       "EIO" is used.
383
384       "nbdkit_error" has the following prototype and works like printf(3):
385
386        void nbdkit_error (const char *fs, ...);
387        void nbdkit_verror (const char *fs, va_list args);
388
389       For convenience, "nbdkit_error" preserves the value of "errno", and
390       also supports the glibc extension of a single %m in a format string
391       expanding to strerror(errno), even on platforms that don't support that
392       natively.
393
394       "nbdkit_set_error" can be called at any time, but only has an impact
395       during callbacks for serving data, and only when the callback returns
396       an indication of failure.  It has the following prototype:
397
398        void nbdkit_set_error (int err);
399

CALLBACKS

401   ".name"
402        const char *name;
403
404       This field (a string) is required, and must contain only ASCII
405       alphanumeric characters or non-leading dashes, and be unique amongst
406       all plugins.
407
408   ".version"
409        const char *version;
410
411       Plugins may optionally set a version string which is displayed in help
412       and debugging output.  (See also "VERSION" below)
413
414   ".longname"
415        const char *longname;
416
417       An optional free text name of the plugin.  This field is used in error
418       messages.
419
420   ".description"
421        const char *description;
422
423       An optional multi-line description of the plugin.
424
425   ".load"
426        void load (void);
427
428       This is called once just after the plugin is loaded into memory.  You
429       can use this to perform any global initialization needed by the plugin.
430
431   ".unload"
432        void unload (void);
433
434       This may be called once just before the plugin is unloaded from memory.
435       Note that it's not guaranteed that ".unload" will always be called (eg.
436       the server might be killed or segfault), so you should try to make the
437       plugin as robust as possible by not requiring cleanup.  See also
438       "SHUTDOWN" below.
439
440   ".dump_plugin"
441        void dump_plugin (void);
442
443       This optional callback is called when the "nbdkit plugin --dump-plugin"
444       command is used.  It should print any additional informative
445       "key=value" fields to stdout as needed.  Prefixing the keys with the
446       name of the plugin will avoid conflicts.
447
448   ".config"
449        int config (const char *key, const char *value);
450
451       On the nbdkit command line, after the plugin filename, come an optional
452       list of "key=value" arguments.  These are passed to the plugin through
453       this callback when the plugin is first loaded and before any
454       connections are accepted.
455
456       This callback may be called zero or more times.
457
458       Both "key" and "value" parameters will be non-NULL.  The strings are
459       owned by nbdkit but will remain valid for the lifetime of the plugin,
460       so the plugin does not need to copy them.
461
462       The key will be a non-empty string beginning with an ASCII alphabetic
463       character ("A-Z" "a-z").  The rest of the key must contain only ASCII
464       alphanumeric plus period, underscore or dash characters ("A-Z" "a-z"
465       "0-9" "." "_" "-").  The value may be an arbitrary string, including an
466       empty string.
467
468       The names of "key"s accepted by plugins is up to the plugin, but you
469       should probably look at other plugins and follow the same conventions.
470
471       If the value is a relative path, then note that the server changes
472       directory when it starts up.  See "FILENAMES AND PATHS" above.
473
474       If "nbdkit_stdio_safe" returns 1, the value of the configuration
475       parameter may be used to trigger reading additional data through stdin
476       (such as a password or inline script).
477
478       If the ".config" callback is not provided by the plugin, and the user
479       tries to specify any "key=value" arguments, then nbdkit will exit with
480       an error.
481
482       If there is an error, ".config" should call "nbdkit_error" with an
483       error message and return -1.
484
485   ".magic_config_key"
486        const char *magic_config_key;
487
488       This optional string can be used to set a "magic" key used when parsing
489       plugin parameters.  It affects how "bare parameters" (those which do
490       not contain an "=" character) are parsed on the command line.
491
492       If "magic_config_key != NULL" then any bare parameters are passed to
493       the ".config" method as: "config (magic_config_key, argv[i]);".
494
495       If "magic_config_key" is not set then we behave as in nbdkit < 1.7: If
496       the first parameter on the command line is bare then it is passed to
497       the ".config" method as: "config ("script", value);".  Any other bare
498       parameters give errors.
499
500   ".config_complete"
501        int config_complete (void);
502
503       This optional callback is called after all the configuration has been
504       passed to the plugin.  It is a good place to do checks, for example
505       that the user has passed the required parameters to the plugin.
506
507       If there is an error, ".config_complete" should call "nbdkit_error"
508       with an error message and return -1.
509
510   ".config_help"
511        const char *config_help;
512
513       This optional multi-line help message should summarize any "key=value"
514       parameters that it takes.  It does not need to repeat what already
515       appears in ".description".
516
517       If the plugin doesn't take any config parameters you should probably
518       omit this.
519
520   ".thread_model"
521        int thread_model (void)
522
523       This optional callback is called after all the configuration has been
524       passed to the plugin.  It can be used to force a stricter thread model
525       based on configuration, compared to "THREAD_MODEL".  See "Threads"
526       above for details.  Attempts to request a looser (more parallel) model
527       are silently ignored.
528
529       If there is an error, ".thread_model" should call "nbdkit_error" with
530       an error message and return -1.
531
532   ".get_ready"
533        int get_ready (void);
534
535       This optional callback is called before the server starts serving.  It
536       is called before the server forks or changes directory.  It is
537       ordinarily the last chance to do any global preparation that is needed
538       to serve connections.
539
540       If there is an error, ".get_ready" should call "nbdkit_error" with an
541       error message and return -1.
542
543   ".after_fork"
544        int after_fork (void);
545
546       This optional callback is called before the server starts serving.  It
547       is called after the server forks and changes directory.  If a plugin
548       needs to create background threads (or uses an external library that
549       creates threads) it should do so here, because background threads are
550       killed by fork.  However you should try to do as little as possible
551       here because error reporting is difficult.  See "Callback lifecycle"
552       above.
553
554       If there is an error, ".after_fork" should call "nbdkit_error" with an
555       error message and return -1.
556
557   ".cleanup"
558        void cleanup (void);
559
560       This optional callback is called after the server has closed all
561       connections and is preparing to unload.  It is only reached in the same
562       cases that the ".after_fork" callback was used, making it a good place
563       to clean up any background threads.  However, it is not guaranteed that
564       this callback will be reached, so you should try to make the plugin as
565       robust as possible by not requiring cleanup.  See also "SHUTDOWN"
566       below.
567
568   ".preconnect"
569        int preconnect (int readonly);
570
571       This optional callback is called when a TCP connection has been made to
572       the server.  This happens early, before NBD or TLS negotiation.  If TLS
573       authentication is required to access the server, then it has not been
574       negotiated at this point.
575
576       For security reasons (to avoid denial of service attacks) this callback
577       should be written to be as fast and take as few resources as possible.
578       If you use this callback, only use it to do basic access control, such
579       as checking "nbdkit_peer_name", "nbdkit_peer_pid", "nbdkit_peer_uid",
580       "nbdkit_peer_gid" against a list of permitted source addresses (see
581       "PEER NAME" and nbdkit-ip-filter(1)).  It may be better to do access
582       control outside the server, for example using TCP wrappers or a
583       firewall.
584
585       The "readonly" flag informs the plugin that the server was started with
586       the -r flag on the command line.
587
588       Returning 0 will allow the connection to continue.  If there is an
589       error or you want to deny the connection, call "nbdkit_error" with an
590       error message and return -1.
591
592   ".list_exports"
593        int list_exports (int readonly, int is_tls,
594                          struct nbdkit_exports *exports);
595
596       This optional callback is called if the client tries to list the
597       exports served by the plugin (using "NBD_OPT_LIST").  If the plugin
598       does not supply this callback then the result of ".default_export" is
599       advertised as the lone export.  The NBD protocol defines "" as the
600       default export, so this is suitable for plugins which ignore the export
601       name and always serve the same content.  See also "EXPORT NAME" below.
602
603       The "readonly" flag informs the plugin that the server was started with
604       the -r flag on the command line, which is the same value passed to
605       ".preconnect" and ".open".  However, the NBD protocol does not yet have
606       a way to let the client advertise an intent to be read-only even when
607       the server allows writes, so this parameter may not be as useful as it
608       appears.
609
610       The "is_tls" flag informs the plugin whether this listing was requested
611       after the client has completed TLS negotiation.  When running the
612       server in a mode that permits but does not require TLS, be careful that
613       any exports listed when "is_tls" is "false" do not leak unintended
614       information.
615
616       The "exports" parameter is an opaque object for collecting the list of
617       exports.  Call "nbdkit_add_export" as needed to add specific exports to
618       the list.
619
620        int nbdkit_add_export (struct nbdkit_export *exports,
621                               const char *name, const char *description);
622
623       The "name" must be a non-NULL, UTF-8 string between 0 and 4096 bytes in
624       length.  Export names must be unique.  "description" is an optional
625       description of the export which some clients can display but which is
626       otherwise unused (if you don't want a description, you can pass this
627       parameter as "NULL").  The string(s) are copied into the exports list
628       so you may free them immediately after calling this function.
629       "nbdkit_add_export" returns 0 on success or -1 on failure; on failure
630       "nbdkit_error" has already been called, with "errno" set to a suitable
631       value.
632
633       There are also situations where a plugin may wish to duplicate the
634       nbdkit default behavior of supplying an export list containing only the
635       result of ".default_export" when ".list_exports" is missing; this is
636       most common in a language binding where it is not known at compile time
637       whether the language script will be providing an implementation for
638       ".list_exports", and is done by calling "nbdkit_use_default_export".
639
640        int nbdkit_use_default_export (struct nbdkit_export *exports);
641
642       "nbdkit_use_default_export" returns 0 on success or -1 on failure; on
643       failure "nbdkit_error" has already been called, with "errno" set to a
644       suitable value.
645
646       The plugin may also leave the export list empty, by not calling either
647       helper.  Once the plugin is happy with the list contents, returning 0
648       will send the list of exports back to the client.  If there is an
649       error, ".list_exports" should call "nbdkit_error" with an error message
650       and return -1.
651
652   ".default_export"
653        const char *default_export (int readonly, int is_tls);
654
655       This optional callback is called if the client tries to connect to the
656       default export "", where the plugin provides a UTF-8 string between 0
657       and 4096 bytes.  If the plugin does not supply this callback, the
658       connection continues with the empty name; if the plugin returns a valid
659       string, nbdkit behaves as if the client had passed that string instead
660       of an empty name, and returns that name to clients that support it (see
661       the "NBD_INFO_NAME" response to "NBD_OPT_GO").  Similarly, if the
662       plugin does not supply a ".list_exports" callback, the result of this
663       callback determines what export name to advertise to a client
664       requesting an export list.
665
666       The "readonly" flag informs the plugin that the server was started with
667       the -r flag on the command line, which is the same value passed to
668       ".preconnect" and ".open".  However, the NBD protocol does not yet have
669       a way to let the client advertise an intent to be read-only even when
670       the server allows writes, so this parameter may not be as useful as it
671       appears.
672
673       The "is_tls" flag informs the plugin whether the canonical name for the
674       default export is being requested after the client has completed TLS
675       negotiation.  When running the server in a mode that permits but does
676       not require TLS, be careful that a default export name does not leak
677       unintended information.
678
679       If the plugin returns "NULL" or an invalid string (such as longer than
680       4096 bytes), the client is not permitted to connect to the default
681       export.  However, this is not an error in the protocol, so it is not
682       necessary to call "nbdkit_error".
683
684   ".open"
685        void *open (int readonly);
686
687       This is called when a new client connects to the nbdkit server.  The
688       callback should allocate a handle and return it.  This handle is passed
689       back to other callbacks and could be freed in the ".close" callback.
690
691       Note that the handle is completely opaque to nbdkit, but it must not be
692       NULL.  If you don't need to use a handle, return
693       "NBDKIT_HANDLE_NOT_NEEDED" which is a static non-NULL pointer.
694
695       The "readonly" flag informs the plugin that the server was started with
696       the -r flag on the command line which forces connections to be read-
697       only.  Note that the plugin may additionally force the connection to be
698       readonly (even if this flag is false) by returning false from the
699       ".can_write" callback.  So if your plugin can only serve read-only, you
700       can ignore this parameter.
701
702       If the plugin wants to differentiate the content it serves based on
703       client input, then this is the spot to use nbdkit_export_name() to
704       determine which export the client requested.  See also "EXPORT NAME"
705       below.
706
707       This callback is called after the NBD handshake has completed; if the
708       server requires TLS authentication, then that has occurred as well.
709       But if the server is set up to have optional TLS authentication, you
710       may check "nbdkit_is_tls" to learn whether the client has completed TLS
711       authentication.  When running the server in a mode that permits but
712       does not require TLS, be careful that you do not allow unauthenticated
713       clients to cause a denial of service against authentication.
714
715       If there is an error, ".open" should call "nbdkit_error" with an error
716       message and return "NULL".
717
718   ".close"
719        void close (void *handle);
720
721       This is called when the client closes the connection.  It should clean
722       up any per-connection resources.
723
724       Note there is no way in the NBD protocol to communicate close errors
725       back to the client, for example if your plugin calls close(2) and you
726       are checking for errors (as you should do).  Therefore the best you can
727       do is to log the error on the server.  Well-behaved NBD clients should
728       try to flush the connection before it is closed and check for errors,
729       but obviously this is outside the scope of nbdkit.
730
731   ".get_size"
732        int64_t get_size (void *handle);
733
734       This is called during the option negotiation phase of the protocol to
735       get the size (in bytes) of the block device being exported.
736
737       The returned size must be ≥ 0.  If there is an error, ".get_size"
738       should call "nbdkit_error" with an error message and return -1.
739
740   ".export_description"
741        const char *export_description (void *handle);
742
743       This is called during the option negotiation phase only if the client
744       specifically requested an export description (see the
745       "NBD_INFO_DESCRIPTION" response to "NBD_OPT_GO").  Any description
746       provided must be human-readable UTF-8, no longer than 4096 bytes.
747       Ideally, this description should match any description set during
748       ".list_exports", but that is not enforced.
749
750       If the plugin returns "NULL" or an invalid string (such as longer than
751       4096 bytes), or if this callback is omitted, no description is offered
752       to the client.  As this is not an error in the protocol, it is not
753       necessary to call "nbdkit_error".  If the callback will not be
754       returning a compile-time constant string, you may find
755       "nbdkit_strdup_intern" helpful for returning a value that avoids a
756       memory leak.
757
758   ".block_size"
759        int block_size (void *handle, uint32_t *minimum,
760                        uint32_t *preferred, uint32_t *maximum);
761
762       This is called during the option negotiation phase of the protocol to
763       get the minimum, preferred and maximum block size (all in bytes) of the
764       block device.  The client should obey these constraints by not making
765       requests which are smaller than the minimum size or larger than the
766       maximum size, and usually making requests of a multiple of the
767       preferred size.  Furthermore requests should be aligned to at least the
768       minimum block size, and usually the preferred block size.
769
770       "Preferred" block size in the NBD specification can be misinterpreted.
771       It means the I/O size which does not have a penalty for read-modify-
772       write.
773
774       Even if the plugin implements this callback, this does not mean that
775       all client requests will obey the constraints.  A client could still
776       ignore the constraints.  nbdkit passes all requests through to the
777       plugin, because what the plugin does depends on the plugin's policy.
778       It might decide to serve the requests correctly anyway, or reject them
779       with an error.  Plugins can avoid this complexity by using
780       nbdkit-blocksize-policy-filter(1) which allows both setting/adjusting
781       the constraints, and selecting an error policy.
782
783       The minimum block size must be ≥ 1.  The maximum block size must be ≤
784       0xffff_ffff.  minimum ≤ preferred ≤ maximum.
785
786       As a special case, the plugin may return minimum == preferred ==
787       maximum == 0, meaning no information.
788
789       If this callback is not used, then the NBD protocol assumes by default
790       minimum = 1, preferred = 4096.  (Maximum block size depends on various
791       factors, see the NBD protocol specification, section "Block size
792       constraints").
793
794   ".can_write"
795        int can_write (void *handle);
796
797       This is called during the option negotiation phase to find out if the
798       handle supports writes.
799
800       If there is an error, ".can_write" should call "nbdkit_error" with an
801       error message and return -1.
802
803       This callback is not required.  If omitted, then we return true iff a
804       ".pwrite" callback has been defined.
805
806   ".can_flush"
807        int can_flush (void *handle);
808
809       This is called during the option negotiation phase to find out if the
810       handle supports the flush-to-disk operation.
811
812       If there is an error, ".can_flush" should call "nbdkit_error" with an
813       error message and return -1.
814
815       This callback is not required.  If omitted, then we return true iff a
816       ".flush" callback has been defined.
817
818   ".is_rotational"
819        int is_rotational (void *handle);
820
821       This is called during the option negotiation phase to find out if the
822       backing disk is a rotational medium (like a traditional hard disk) or
823       not (like an SSD).  If true, this may cause the client to reorder
824       requests to make them more efficient for a slow rotating disk.
825
826       If there is an error, ".is_rotational" should call "nbdkit_error" with
827       an error message and return -1.
828
829       This callback is not required.  If omitted, then we return false.
830
831   ".can_trim"
832        int can_trim (void *handle);
833
834       This is called during the option negotiation phase to find out if the
835       plugin supports the trim/discard operation for punching holes in the
836       backing storage.
837
838       If there is an error, ".can_trim" should call "nbdkit_error" with an
839       error message and return -1.
840
841       This callback is not required.  If omitted, then we return true iff a
842       ".trim" callback has been defined.
843
844   ".can_zero"
845        int can_zero (void *handle);
846
847       This is called during the option negotiation phase to find out if the
848       plugin wants the ".zero" callback to be utilized.  Support for writing
849       zeroes is still advertised to the client (unless the
850       nbdkit-nozero-filter(1) is also used), so returning false merely serves
851       as a way to avoid complicating the ".zero" callback to have to fail
852       with "ENOTSUP" or "EOPNOTSUPP" on the connections where it will never
853       be more efficient than using ".pwrite" up front.
854
855       If there is an error, ".can_zero" should call "nbdkit_error" with an
856       error message and return -1.
857
858       This callback is not required.  If omitted, then for a normal zero
859       request, nbdkit always tries ".zero" first if it is present, and
860       gracefully falls back to ".pwrite" if ".zero" was absent or failed with
861       "ENOTSUP" or "EOPNOTSUPP".
862
863   ".can_fast_zero"
864        int can_fast_zero (void *handle);
865
866       This is called during the option negotiation phase to find out if the
867       plugin wants to advertise support for fast zero requests.  If this
868       support is not advertised, a client cannot attempt fast zero requests,
869       and has no way to tell if writing zeroes offers any speedups compared
870       to using ".pwrite" (other than compressed network traffic).  If support
871       is advertised, then ".zero" will have "NBDKIT_FLAG_FAST_ZERO" set when
872       the client has requested a fast zero, in which case the plugin must
873       fail with "ENOTSUP" or "EOPNOTSUPP" up front if the request would not
874       offer any benefits over ".pwrite".  Advertising support for fast zero
875       requests does not require that writing zeroes be fast, only that the
876       result (whether success or failure) is fast, so this should be
877       advertised when feasible.
878
879       If there is an error, ".can_fast_zero" should call "nbdkit_error" with
880       an error message and return -1.
881
882       This callback is not required.  If omitted, then nbdkit returns true if
883       ".zero" is absent or ".can_zero" returns false (in those cases, nbdkit
884       fails all fast zero requests, as its fallback to ".pwrite" is not
885       inherently faster), otherwise false (since it cannot be determined in
886       advance if the plugin's ".zero" will properly honor the semantics of
887       "NBDKIT_FLAG_FAST_ZERO").
888
889   ".can_extents"
890        int can_extents (void *handle);
891
892       This is called during the option negotiation phase to find out if the
893       plugin supports detecting allocated (non-sparse) regions of the disk
894       with the ".extents" callback.
895
896       If there is an error, ".can_extents" should call "nbdkit_error" with an
897       error message and return -1.
898
899       This callback is not required.  If omitted, then we return true iff a
900       ".extents" callback has been defined.
901
902   ".can_fua"
903        int can_fua (void *handle);
904
905       This is called during the option negotiation phase to find out if the
906       plugin supports the Forced Unit Access (FUA) flag on write, zero, and
907       trim requests.  If this returns "NBDKIT_FUA_NONE", FUA support is not
908       advertised to the client; if this returns "NBDKIT_FUA_EMULATE", the
909       ".flush" callback must work (even if ".can_flush" returns false), and
910       FUA support is emulated by calling ".flush" after any write operation;
911       if this returns "NBDKIT_FUA_NATIVE", then the ".pwrite", ".zero", and
912       ".trim" callbacks (if implemented) must handle the flag
913       "NBDKIT_FLAG_FUA", by not returning until that action has landed in
914       persistent storage.
915
916       If there is an error, ".can_fua" should call "nbdkit_error" with an
917       error message and return -1.
918
919       This callback is not required unless a plugin wants to specifically
920       handle FUA requests.  If omitted, nbdkit checks whether ".flush"
921       exists, and behaves as if this function returns "NBDKIT_FUA_NONE" or
922       "NBDKIT_FUA_EMULATE" as appropriate.
923
924   ".can_multi_conn"
925        int can_multi_conn (void *handle);
926
927       This is called during the option negotiation phase to find out if the
928       plugin is prepared to handle multiple connections from a single client.
929       If the plugin sets this to true then a client may try to open multiple
930       connections to the nbdkit server and spread requests across all
931       connections to maximize parallelism.  If the plugin sets it to false
932       (which is the default) then well-behaved clients should only open a
933       single connection, although we cannot control what clients do in
934       practice.
935
936       Specifically it means that either the plugin does not cache requests at
937       all.  Or if it does cache them then the effects of a ".flush" request
938       or setting "NBDKIT_FLAG_FUA" on a request must be visible across all
939       connections to the plugin before the plugin replies to that request.
940
941       Properly working clients should send the same export name for each of
942       these connections.
943
944       If you use Linux nbd-client(8) option -C num with num > 1 then Linux
945       checks this flag and will refuse to connect if ".can_multi_conn" is
946       false.
947
948       If there is an error, ".can_multi_conn" should call "nbdkit_error" with
949       an error message and return -1.
950
951       This callback is not required.  If omitted, then we return false.
952
953   ".can_cache"
954        int can_cache (void *handle);
955
956       This is called during the option negotiation phase to find out if the
957       plugin supports a cache or prefetch operation.
958
959       This can return:
960
961       "NBDKIT_CACHE_NONE"
962           Cache support is not advertised to the client.
963
964       "NBDKIT_CACHE_EMULATE"
965           Caching is emulated by the server calling ".pread" and discarding
966           the result.
967
968       "NBDKIT_CACHE_NATIVE"
969           Cache support is advertised to the client.  The ".cache" callback
970           will be called if it exists, otherwise all cache requests instantly
971           succeed.
972
973       If there is an error, ".can_cache" should call "nbdkit_error" with an
974       error message and return -1.
975
976       This callback is not required.  If omitted, then we return
977       "NBDKIT_CACHE_NONE" if the ".cache" callback is missing, or
978       "NBDKIT_CACHE_NATIVE" if it is defined.
979
980   ".pread"
981        int pread (void *handle, void *buf, uint32_t count, uint64_t offset,
982                   uint32_t flags);
983
984       During the data serving phase, nbdkit calls this callback to read data
985       from the backing store.  "count" bytes starting at "offset" in the
986       backing store should be read and copied into "buf".  nbdkit takes care
987       of all bounds- and sanity-checking, so the plugin does not need to
988       worry about that.
989
990       The parameter "flags" exists in case of future NBD protocol extensions;
991       at this time, it will be 0 on input.
992
993       The callback must read the whole "count" bytes if it can.  The NBD
994       protocol doesn't allow partial reads (instead, these would be errors).
995       If the whole "count" bytes was read, the callback should return 0 to
996       indicate there was no error.
997
998       If there is an error (including a short read which couldn't be
999       recovered from), ".pread" should call "nbdkit_error" with an error
1000       message, and "nbdkit_set_error" to record an appropriate error (unless
1001       "errno" is sufficient), then return -1.
1002
1003   ".pwrite"
1004        int pwrite (void *handle, const void *buf, uint32_t count, uint64_t offset,
1005                    uint32_t flags);
1006
1007       During the data serving phase, nbdkit calls this callback to write data
1008       to the backing store.  "count" bytes starting at "offset" in the
1009       backing store should be written using the data in "buf".  nbdkit takes
1010       care of all bounds- and sanity-checking, so the plugin does not need to
1011       worry about that.
1012
1013       This function will not be called if ".can_write" returned false.  The
1014       parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on the
1015       result of ".can_fua".
1016
1017       The callback must write the whole "count" bytes if it can.  The NBD
1018       protocol doesn't allow partial writes (instead, these would be errors).
1019       If the whole "count" bytes was written successfully, the callback
1020       should return 0 to indicate there was no error.
1021
1022       If there is an error (including a short write which couldn't be
1023       recovered from), ".pwrite" should call "nbdkit_error" with an error
1024       message, and "nbdkit_set_error" to record an appropriate error (unless
1025       "errno" is sufficient), then return -1.
1026
1027   ".flush"
1028        int flush (void *handle, uint32_t flags);
1029
1030       During the data serving phase, this callback is used to fdatasync(2)
1031       the backing store, ie. to ensure it has been completely written to a
1032       permanent medium.  If that is not possible then you can omit this
1033       callback.
1034
1035       This function will not be called directly by the client if ".can_flush"
1036       returned false; however, it may still be called by nbdkit if ".can_fua"
1037       returned "NBDKIT_FUA_EMULATE".  The parameter "flags" exists in case of
1038       future NBD protocol extensions; at this time, it will be 0 on input.
1039
1040       If there is an error, ".flush" should call "nbdkit_error" with an error
1041       message, and "nbdkit_set_error" to record an appropriate error (unless
1042       "errno" is sufficient), then return -1.
1043
1044   ".trim"
1045        int trim (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
1046
1047       During the data serving phase, this callback is used to "punch holes"
1048       in the backing store.  If that is not possible then you can omit this
1049       callback.
1050
1051       This function will not be called if ".can_trim" returned false.  The
1052       parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on the
1053       result of ".can_fua".
1054
1055       If there is an error, ".trim" should call "nbdkit_error" with an error
1056       message, and "nbdkit_set_error" to record an appropriate error (unless
1057       "errno" is sufficient), then return -1.
1058
1059   ".zero"
1060        int zero (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
1061
1062       During the data serving phase, this callback is used to write "count"
1063       bytes of zeroes at "offset" in the backing store.
1064
1065       This function will not be called if ".can_zero" returned false.  On
1066       input, the parameter "flags" may include "NBDKIT_FLAG_MAY_TRIM"
1067       unconditionally, "NBDKIT_FLAG_FUA" based on the result of ".can_fua",
1068       and "NBDKIT_FLAG_FAST_ZERO" based on the result of ".can_fast_zero".
1069
1070       If "NBDKIT_FLAG_MAY_TRIM" is requested, the operation can punch a hole
1071       instead of writing actual zero bytes, but only if subsequent reads from
1072       the hole read as zeroes.
1073
1074       If "NBDKIT_FLAG_FAST_ZERO" is requested, the plugin must decide up
1075       front if the implementation is likely to be faster than a corresponding
1076       ".pwrite"; if not, then it must immediately fail with "ENOTSUP" or
1077       "EOPNOTSUPP" (whether by "nbdkit_set_error" or "errno") and preferably
1078       without modifying the exported image.  It is acceptable to always fail
1079       a fast zero request (as a fast failure is better than attempting the
1080       write only to find out after the fact that it was not fast after all).
1081       Note that on Linux, support for ioctl(BLKZEROOUT) is insufficient for
1082       determining whether a zero request to a block device will be fast
1083       (because the kernel will perform a slow fallback when needed).
1084
1085       The callback must write the whole "count" bytes if it can.  The NBD
1086       protocol doesn't allow partial writes (instead, these would be errors).
1087       If the whole "count" bytes was written successfully, the callback
1088       should return 0 to indicate there was no error.
1089
1090       If there is an error, ".zero" should call "nbdkit_error" with an error
1091       message, and "nbdkit_set_error" to record an appropriate error (unless
1092       "errno" is sufficient), then return -1.
1093
1094       If this callback is omitted, or if it fails with "ENOTSUP" or
1095       "EOPNOTSUPP" (whether by "nbdkit_set_error" or "errno"), then ".pwrite"
1096       will be used as an automatic fallback except when the client requested
1097       a fast zero.
1098
1099   ".extents"
1100        int extents (void *handle, uint32_t count, uint64_t offset,
1101                     uint32_t flags, struct nbdkit_extents *extents);
1102
1103       During the data serving phase, this callback is used to detect
1104       allocated, sparse and zeroed regions of the disk.
1105
1106       This function will not be called if ".can_extents" returned false.
1107       nbdkit's default behaviour in this case is to treat the whole virtual
1108       disk as if it was allocated.  Also, this function will not be called by
1109       a client that does not request structured replies (the --no-sr option
1110       of nbdkit can be used to test behavior when ".extents" is unavailable
1111       to the client).
1112
1113       The callback should detect and return the list of extents overlapping
1114       the range "[offset...offset+count-1]".  The "extents" parameter points
1115       to an opaque object which the callback should fill in by calling
1116       "nbdkit_add_extent".  See "Extents list" below.
1117
1118       If there is an error, ".extents" should call "nbdkit_error" with an
1119       error message, and "nbdkit_set_error" to record an appropriate error
1120       (unless "errno" is sufficient), then return -1.
1121
1122       Extents list
1123
1124       The plugin "extents" callback is passed an opaque pointer "struct
1125       nbdkit_extents *extents".  This structure represents a list of
1126       filesystem extents describing which areas of the disk are allocated,
1127       which are sparse (“holes”), and, if supported, which are zeroes.
1128
1129       The "extents" callback should scan the disk starting at "offset" and
1130       call "nbdkit_add_extent" for each extent found.
1131
1132       Extents overlapping the range "[offset...offset+count-1]" should be
1133       returned if possible.  However nbdkit ignores extents < offset so the
1134       plugin may, if it is easier to implement, return all extent information
1135       for the whole disk.  The plugin may return extents beyond the end of
1136       the range.  It may also return extent information for less than the
1137       whole range, but it must return at least one extent overlapping
1138       "offset".
1139
1140       The extents must be added in ascending order, and must be contiguous.
1141
1142       The "flags" parameter of the ".extents" callback may contain the flag
1143       "NBDKIT_FLAG_REQ_ONE".  This means that the client is only requesting
1144       information about the extent overlapping "offset".  The plugin may
1145       ignore this flag, or as an optimization it may return just a single
1146       extent for "offset".
1147
1148        int nbdkit_add_extent (struct nbdkit_extents *extents,
1149                               uint64_t offset, uint64_t length, uint32_t type);
1150
1151       Add an extent covering "[offset...offset+length-1]" of one of the
1152       following four types:
1153
1154       "type = 0"
1155           A normal, allocated data extent.
1156
1157       "type = NBDKIT_EXTENT_HOLE|NBDKIT_EXTENT_ZERO"
1158           An unallocated extent, a.k.a. a “hole”, which reads back as zeroes.
1159           This is the normal type of hole applicable to most disks.
1160
1161       "type = NBDKIT_EXTENT_ZERO"
1162           An allocated extent which is known to contain only zeroes.
1163
1164       "type = NBDKIT_EXTENT_HOLE"
1165           An unallocated extent (hole) which does not read back as zeroes.
1166           Note this should only be used in specialized circumstances such as
1167           when writing a plugin for (or to emulate) certain SCSI drives which
1168           do not guarantee that trimmed blocks read back as zeroes.
1169
1170       "nbdkit_add_extent" returns 0 on success or -1 on failure.  On failure
1171       "nbdkit_error" and/or "nbdkit_set_error" has already been called.
1172       "errno" will be set to a suitable value.
1173
1174   ".cache"
1175        int cache (void *handle, uint32_t count, uint64_t offset, uint32_t flags);
1176
1177       During the data serving phase, this callback is used to give the plugin
1178       a hint that the client intends to make further accesses to the given
1179       region of the export.
1180
1181       The nature of caching/prefetching is not specified further by the NBD
1182       specification.  For example, a server may place limits on how much may
1183       be cached at once, and there is no way to control if writes to a cached
1184       area have write-through or write-back semantics.  In fact, the cache
1185       command can always fail and still be compliant, and success might not
1186       guarantee a performance gain.
1187
1188       If this callback is omitted, then the results of ".can_cache" determine
1189       whether nbdkit will reject cache requests, treat them as instant
1190       success, or emulate caching by calling ".pread" over the same region
1191       and ignoring the results.
1192
1193       This function will not be called if ".can_cache" did not return
1194       "NBDKIT_CACHE_NATIVE".
1195
1196       The "flags" parameter exists in case of future NBD protocol extensions;
1197       at this time, it will be 0 on input.  A plugin must fail this function
1198       if "flags" includes an unrecognized flag, as that may indicate a
1199       requirement that the plugin must comply with to provide a specific
1200       caching semantic.
1201
1202       If there is an error, ".cache" should call "nbdkit_error" with an error
1203       message, and "nbdkit_set_error" to record an appropriate error (unless
1204       "errno" is sufficient), then return -1.
1205
1206   ".errno_is_preserved"
1207       This field defaults to 0; if non-zero, nbdkit can reliably use the
1208       value of "errno" when a callback reports failure, rather than the
1209       plugin having to call "nbdkit_set_error".
1210

SHUTDOWN

1212       When nbdkit receives certain signals it will shut down (see "SIGNALS"
1213       in nbdkit(1)).  The server will wait for any currently running plugin
1214       callbacks to finish, call ".close" on those connections, then call the
1215       ".cleanup" and ".unload" callbacks before unloading the plugin.
1216
1217       Note that it's not guaranteed this can always happen (eg. the server
1218       might be killed by "SIGKILL" or segfault).
1219
1220   Requesting asynchronous shutdown
1221       Plugins and filters can call exit(3) in the configuration phase (before
1222       and including ".get_ready", but not in connected callbacks).
1223
1224       Once nbdkit has started serving connections, plugins and filters should
1225       not call exit(3).  However they may instruct nbdkit to shut down by
1226       calling "nbdkit_shutdown", or to disconnect a single client by calling
1227       "nbdkit_disconnect":
1228
1229        void nbdkit_shutdown (void);
1230
1231       This function requests an asynchronous shutdown and returns (note that
1232       it does not exit the process immediately).  It ensures that the plugin
1233       and all filters are unloaded cleanly which may take some time.  Further
1234       callbacks from nbdkit into the plugin or filter may occur after you
1235       have called this.
1236
1237        void nbdkit_disconnect (int force);
1238
1239       This function requests that the current connection be disconnected
1240       (note that it does not affect other connections, and the client may try
1241       to reconnect).  It is only useful from connected callbacks (that is,
1242       after ".open" and before ".close").  If "force" is true, nbdkit will
1243       disconnect the client immediately, and the client will not receive any
1244       response to the current command or any other commands in flight in
1245       parallel threads; otherwise, nbdkit will not accept any new commands
1246       from the client (failing all commands other than "NBD_CMD_DISC" with
1247       "ESHUTDOWN"), but will allow existing commands to complete gracefully.
1248       Either way, the next callback for the current connection should be
1249       ".close".
1250

PARSING COMMAND LINE PARAMETERS

1252   Parsing numbers
1253       There are several functions for parsing numbers.  These all deal
1254       correctly with overflow, out of range and parse errors, and you should
1255       use them instead of unsafe functions like sscanf(3), atoi(3) and
1256       similar.
1257
1258        int nbdkit_parse_int (const char *what, const char *str, int *r);
1259        int nbdkit_parse_unsigned (const char *what,
1260                                   const char *str, unsigned *r);
1261        int nbdkit_parse_int8_t (const char *what,
1262                                 const char *str, int8_t *r);
1263        int nbdkit_parse_uint8_t (const char *what,
1264                                  const char *str, uint8_t *r);
1265        int nbdkit_parse_int16_t (const char *what,
1266                                  const char *str, int16_t *r);
1267        int nbdkit_parse_uint16_t (const char *what,
1268                                   const char *str, uint16_t *r);
1269        int nbdkit_parse_int32_t (const char *what,
1270                                  const char *str, int32_t *r);
1271        int nbdkit_parse_uint32_t (const char *what,
1272                                   const char *str, uint32_t *r);
1273        int nbdkit_parse_int64_t (const char *what,
1274                                  const char *str, int64_t *r);
1275        int nbdkit_parse_uint64_t (const char *what,
1276                                   const char *str, uint64_t *r);
1277
1278       Parse string "str" into an integer of various types.  These functions
1279       parse a decimal, hexadecimal ("0x...") or octal ("0...") number.
1280
1281       On success the functions return 0 and set *r to the parsed value
1282       (unless "*r == NULL" in which case the result is discarded).  On error,
1283       "nbdkit_error" is called and the functions return -1.  On error *r is
1284       always unchanged.
1285
1286       The "what" parameter is printed in error messages to provide context.
1287       It should usually be a short descriptive string of what you are trying
1288       to parse, eg:
1289
1290        if (nbdkit_parse_int ("random seed", value, &seed) == -1)
1291          return -1;
1292
1293       might print an error:
1294
1295        random seed: could not parse number: "lalala"
1296
1297   Parsing sizes
1298       Use the "nbdkit_parse_size" utility function to parse human-readable
1299       size strings such as "100M" into the size in bytes.
1300
1301        int64_t nbdkit_parse_size (const char *str);
1302
1303       "str" can be a string in a number of common formats.  The function
1304       returns the size in bytes.  If there was an error, it returns -1.
1305
1306   Parsing booleans
1307       Use the "nbdkit_parse_bool" utility function to parse human-readable
1308       strings such as "on" into a boolean value.
1309
1310        int nbdkit_parse_bool (const char *str);
1311
1312       "str" can be a string containing a case-insensitive form of various
1313       common toggle values.  The function returns 0 or 1 if the parse was
1314       successful.  If there was an error, it returns -1.
1315
1316   Parsing probabilities
1317       Use the "nbdkit_parse_probability" utility function to parse
1318       probabilities.  Common formats understood include: "0.1", "1e-1",
1319       "10%", "1:10" or "1/10", which all mean a probability of 1 in 10.
1320
1321        int nbdkit_parse_probability (const char *what, const char *str,
1322                                      double *ret);
1323
1324       The "what" parameter is printed in error messages to provide context.
1325       The "str" parameter is the probability string.
1326
1327       On success the function returns 0 and sets *ret.  The probability is
1328       always a finite number ≥ 0.0, but note the result may be larger than
1329       1.0 (for example if "str == "200%"" then the function will set
1330       "*ret = 2.0").  If you want to clamp the upper bound the caller must do
1331       that.
1332
1333       On error, nbdkit_error is called and -1 is returned.
1334
1335   Reading passwords
1336       The "nbdkit_read_password" utility function can be used to read
1337       passwords from config parameters:
1338
1339        int nbdkit_read_password (const char *value, char **password);
1340
1341       For example:
1342
1343        char *password = NULL;
1344
1345        static int
1346        myplugin_config (const char *key, const char *value)
1347        {
1348          ..
1349          if (strcmp (key, "password") == 0) {
1350            free (password);
1351            if (nbdkit_read_password (value, &password) == -1)
1352              return -1;
1353          }
1354          ..
1355        }
1356
1357       The "password" result string is allocated by malloc, and so you may
1358       need to free it.
1359
1360       This function recognizes several password formats.  A password may be
1361       used directly on the command line, eg:
1362
1363        nbdkit myplugin password=mostsecret
1364
1365       But more securely this function can also read a password interactively:
1366
1367        nbdkit myplugin password=-
1368
1369       or from a file:
1370
1371        nbdkit myplugin password=+/tmp/secret
1372
1373       or from a file descriptor inherited by nbdkit:
1374
1375        nbdkit myplugin password=-99
1376
1377       Notes on reading passwords
1378
1379       If the password begins with a "-" or "+" character then it must be
1380       passed in a file.
1381
1382       "password=-" can only be used when stdin is a terminal.
1383
1384       "password=-FD" cannot be used with stdin, stdout or stderr (ie. -0, -1
1385       or -2).  The reason is that after reading the password the file
1386       descriptor is closed, which causes bad stuff to happen.
1387
1388   Safely interacting with stdin and stdout
1389        int nbdkit_stdio_safe (void);
1390
1391       The "nbdkit_stdio_safe" utility function returns 1 if it is safe to
1392       interact with stdin and stdout during the configuration phase, and 0
1393       otherwise.  This is because when the nbdkit -s option is used the
1394       plugin must not directly interact with stdin, because that would
1395       interfere with the client.
1396
1397       The result of this function only matters in callbacks up to
1398       ".config_complete".  Once nbdkit reaches ".get_ready", the plugin
1399       should assume that nbdkit may have closed the original stdin and stdout
1400       in order to become a daemon.
1401
1402       nbdkit-sh-plugin(3) uses this function to determine whether it is safe
1403       to support "script=-" to read a script from stdin.  Also constructs
1404       like "password=-" (see "Reading passwords" above) are disabled when
1405       reading from stdio is not safe.
1406

FILENAMES AND PATHS

1408       The server usually (not always) changes directory to "/" before it
1409       starts serving connections.  This means that any relative paths passed
1410       during configuration will not work when the server is running (example:
1411       "nbdkit plugin.so disk.img").
1412
1413       To avoid problems, prepend relative paths with the current directory
1414       before storing them in the handle.  Or open files and store the file
1415       descriptor.
1416
1417   "nbdkit_absolute_path"
1418        char *nbdkit_absolute_path (const char *filename);
1419
1420       The utility function "nbdkit_absolute_path" converts any path to an
1421       absolute path: if it is relative, then all this function does is
1422       prepend the current working directory to the path, with no extra
1423       checks.
1424
1425       Note that this function works only when used in the ".config",
1426       ".config_complete" and ".get_ready" callbacks.
1427
1428       If conversion was not possible, this calls "nbdkit_error" and returns
1429       "NULL".  Note that this function does not check that the file exists.
1430
1431       The returned string must be freed by the caller.
1432
1433   "nbdkit_realpath"
1434        char *nbdkit_realpath (const char *filename);
1435
1436       The utility function "nbdkit_realpath" converts any path to an absolute
1437       path, resolving symlinks.  Under the hood it uses the "realpath"
1438       function, and thus it fails if the path does not exist, or it is not
1439       possible to access to any of the components of the path.
1440
1441       Note that this function works only when used in the ".config",
1442       ".config_complete" and ".get_ready" callbacks.
1443
1444       If the path resolution was not possible, this calls "nbdkit_error" and
1445       returns "NULL".
1446
1447       The returned string must be freed by the caller.
1448
1449   umask
1450       All plugins will see a umask(2) of 0022.
1451

SLEEPING

1453       A plugin that needs to sleep may call sleep(2), nanosleep(2) and
1454       similar.  However that can cause nbdkit to delay excessively when
1455       shutting down (since it must wait for any plugin or filter which is
1456       sleeping).  To avoid this there is a special wrapper around nanosleep
1457       which plugins and filters should use instead.
1458
1459   "nbdkit_nanosleep"
1460        int nbdkit_nanosleep (unsigned sec, unsigned nsec);
1461
1462       The utility function "nbdkit_nanosleep" suspends the current thread,
1463       and returns 0 if it slept at least as many seconds and nanoseconds as
1464       requested, or -1 after calling "nbdkit_error" if there is no point in
1465       continuing the current command.  Attempts to sleep more than "INT_MAX"
1466       seconds are treated as an error.
1467

EXPORT NAME

1469       If the client negotiated an NBD export name with nbdkit then plugins
1470       may read this from any connected callbacks.  Nbdkit's normal behaviour
1471       is to accept any export name passed by the client, log it in debug
1472       output, but otherwise ignore it.  By using "nbdkit_export_name" plugins
1473       may choose to filter by export name or serve different content.
1474
1475   "nbdkit_export_name"
1476        const char *nbdkit_export_name (void);
1477
1478       Return the optional NBD export name if one was negotiated with the
1479       current client (this uses thread-local magic so no parameter is
1480       required).  The returned string is valid at least through the ".close"
1481       of the current connection, but if you need to store it in the plugin
1482       for use by more than one client you must copy it.
1483
1484       The export name is a free-form text string, it is not necessarily a
1485       path or filename and it does not need to begin with a '/' character.
1486       The NBD protocol describes the empty string ("") as a representing a
1487       "default export" or to be used in cases where the export name does not
1488       make sense.  The export name is untrusted client data, be cautious when
1489       parsing it.
1490
1491       On error, "nbdkit_error" is called and the call returns "NULL".
1492

STRING LIFETIME

1494       Some callbacks are specified to return "const char *", even when a
1495       plugin may not have a suitable compile-time constant to return.
1496       Returning dynamically-allocated memory for such a callback would induce
1497       a memory leak or otherwise complicate the plugin to perform additional
1498       bookkeeping.  For these cases, nbdkit provides several convenience
1499       functions for creating a copy of a string for better lifetime
1500       management.
1501
1502   "nbdkit_strdup_intern"
1503   "nbdkit_strndup_intern"
1504        const char *nbdkit_strdup_intern (const char *str);
1505        const char *nbdkit_strndup_intern (const char *str, size_t n);
1506
1507       Returns a copy of "str", possibly limited to a maximum of "n" bytes, so
1508       that the caller may reclaim str and use the copy in its place.  If the
1509       copy is created outside the scope of a connection (such as during
1510       ".load" or ".config"), the lifetime of the copy will last at least
1511       through ".unload".  If the copy is created after a client has triggered
1512       a connection (such as during ".preconnect" or ".open"), the lifetime
1513       will last at least through ".close", but the copy is not safe to share
1514       with other connections.
1515
1516       On error, "nbdkit_error" is called and the call returns "NULL".
1517
1518   "nbdkit_printf_intern"
1519   "nbdkit_vprintf_intern"
1520        const char *nbdkit_printf_intern (const char *fmt, ...);
1521        const char *nbdkit_vprintf_intern (const char *fmt, va_list ap);
1522
1523       Return a string created from a format template, with a lifetime longer
1524       than the current connection.  Shorthand for passing "fmt" to
1525       asprintf(3) on a temporary string, then passing that result to
1526       "nbdkit_strdup_intern".
1527
1528       On error, "nbdkit_error" is called and the call returns "NULL".
1529

AUTHENTICATION

1531       A server may use "nbdkit_is_tls" to limit which export names work until
1532       after a client has completed TLS authentication.  See nbdkit-tls(1).
1533       It is also possible to use nbdkit-tls-fallback-filter(1) to
1534       automatically ensure that the plugin is only used with authentication.
1535
1536   "nbdkit_is_tls"
1537        int nbdkit_is_tls (void);
1538
1539       Return true if the client has completed TLS authentication, or false if
1540       the connection is still plaintext.
1541
1542       On error (such as calling this function outside of the context of
1543       ".open"), "nbdkit_error" is called and the call returns -1.
1544

PEER NAME

1546       It is possible to get the source address of the client when you are
1547       running in any connected callback.
1548
1549   "nbdkit_peer_name"
1550        int nbdkit_peer_name (struct sockaddr *addr, socklen_t *addrlen);
1551
1552       Return the peer (client) address, if available.  The "addr" and
1553       "addrlen" parameters behave like getpeername(2).  In particular you
1554       must initialize "addrlen" with the size of the buffer pointed to by
1555       "addr", and if "addr" is not large enough then the address will be
1556       truncated.
1557
1558       In some cases this is not available or the address returned will be
1559       meaningless (eg. if there is a proxy between the client and nbdkit).
1560       This call uses thread-local magic so no parameter is required to
1561       specify the current connection.
1562
1563       On success this returns 0.  On error, "nbdkit_error" is called and this
1564       call returns -1.
1565
1566   "nbdkit_peer_pid"
1567       (nbdkit ≥ 1.24, Linux only)
1568
1569        int64_t nbdkit_peer_pid (void);
1570
1571       Return the peer process ID.  This is only available when the client
1572       connected over a Unix domain socket.
1573
1574       On success this returns the peer process ID.  On error, "nbdkit_error"
1575       is called and this call returns -1.
1576
1577   "nbdkit_peer_uid"
1578       (nbdkit ≥ 1.24)
1579
1580        int64_t nbdkit_peer_uid (void);
1581
1582       Return the peer user ID.  This is only available when the client
1583       connected over a Unix domain socket.
1584
1585       On success this returns the user ID.  On error, "nbdkit_error" is
1586       called and this call returns -1.
1587
1588   "nbdkit_peer_gid"
1589       (nbdkit ≥ 1.24)
1590
1591        int64_t nbdkit_peer_gid (void);
1592
1593       Return the peer group ID.  This is only available when the client
1594       connected over a Unix domain socket.
1595
1596       On success this returns the user ID.  On error, "nbdkit_error" is
1597       called and this call returns -1.
1598
1599   "nbdkit_peer_security_context"
1600       (nbdkit ≥ 1.36, not Windows)
1601
1602        char *nbdkit_peer_security_context (void);
1603
1604       Return the peer security context (usually the SELinux label, IPSEC
1605       label or NetLabel, see the description of "SO_PEERSEC" in unix(7) and
1606       ip(7).
1607
1608       On success this returns the security context as a string.  The caller
1609       must free the string.  On error (which can include missing label or
1610       unsupported protocol), "nbdkit_error" is called and this call returns
1611       "NULL".
1612

VERSION

1614   Compile-time version of nbdkit
1615       The macros "NBDKIT_VERSION_MAJOR", "NBDKIT_VERSION_MINOR" and
1616       "NBDKIT_VERSION_MICRO" expand to integers containing the version of the
1617       nbdkit headers that you are compiling against.
1618
1619       "NBDKIT_VERSION_MAJOR" is always 1.  "NBDKIT_VERSION_MINOR" is even for
1620       stable releases of nbdkit and odd for development releases.
1621
1622       The macro "NBDKIT_VERSION_STRING" expands to the same version as a
1623       string.
1624
1625   Run-time version of nbdkit
1626       When the plugin is loaded into nbdkit, it may not be the same version
1627       that it was compiled against.  nbdkit guarantees backwards
1628       compatibility of the API and ABI, so provided that nbdkit is the same
1629       version or newer, the plugin will still work.  There is no way to get
1630       the version of nbdkit from the plugin.
1631
1632   Version of the plugin
1633       The plugin itself can use any versioning scheme you want, and put any
1634       string into the ".version" field of the plugin struct (or leave the
1635       field NULL).
1636
1637   API version
1638       See "WRITING AN NBDKIT PLUGIN" above.
1639

DEBUGGING

1641       Run the server with -f and -v options so it doesn't fork and you can
1642       see debugging information:
1643
1644        nbdkit -fv ./myplugin.so [key=value [key=value [...]]]
1645
1646       To print debugging information from within the plugin, call
1647       "nbdkit_debug", which has the following prototype and works like
1648       printf(3):
1649
1650        void nbdkit_debug (const char *fs, ...);
1651        void nbdkit_vdebug (const char *fs, va_list args);
1652
1653       For convenience, "nbdkit_debug" preserves the value of "errno", and
1654       also supports the glibc extension of a single %m in a format string
1655       expanding to strerror(errno), even on platforms that don't support that
1656       natively. Note that "nbdkit_debug" only prints things when the server
1657       is in verbose mode (-v option).
1658
1659   Debug Flags
1660       The -v option switches general debugging on or off, and this debugging
1661       should be used for messages which are useful for all users of your
1662       plugin.
1663
1664       In cases where you want to enable specific extra debugging to track
1665       down bugs in plugins or filters — mainly for use by the plugin/filter
1666       developers themselves — you can define Debug Flags.  These are global
1667       ints called "myplugin_debug_*":
1668
1669        int myplugin_debug_foo;
1670        int myplugin_debug_bar;
1671        ...
1672        if (myplugin_debug_foo) {
1673          nbdkit_debug ("lots of extra debugging about foo: ...");
1674        }
1675
1676       Debug Flags can be controlled on the command line using the -D (or
1677       --debug) option:
1678
1679        nbdkit -f -v -D myplugin.foo=1 -D myplugin.bar=2 myplugin [...]
1680
1681       Note "myplugin" is the name passed to ".name" in the "struct
1682       nbdkit_plugin".
1683
1684       You should only use this feature for debug settings.  For general
1685       settings use ordinary plugin parameters.  Debug Flags can only be C
1686       ints.  They are not supported by non-C language plugins.
1687
1688       For convenience '.' characters are replaced with '_' characters in the
1689       variable name, so both of these parameters:
1690
1691        -D myplugin.foo_bar=1
1692        -D myplugin.foo.bar=1
1693
1694       correspond to the plugin variable "myplugin_debug_foo_bar".
1695

COMPILING THE PLUGIN

1697       Plugins should be compiled as shared libraries.  There are various ways
1698       to achieve this, but most Linux compilers support a -shared option to
1699       create the shared library directly, for example:
1700
1701        gcc -fPIC -shared myplugin.c -o myplugin.so
1702
1703       Note that the shared library will have undefined symbols for functions
1704       that you call like "nbdkit_parse_int" or "nbdkit_error".  These will be
1705       resolved by the server binary when nbdkit dlopens the plugin.
1706
1707   PKG-CONFIG/PKGCONF
1708       nbdkit provides a pkg-config/pkgconf file called "nbdkit.pc" which
1709       should be installed on the correct path when the nbdkit plugin
1710       development environment is installed.  You can use this in autoconf
1711       configure.ac scripts to test for the development environment:
1712
1713        PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])
1714
1715       The above will fail unless nbdkit ≥ 1.2.3 and the header file is
1716       installed, and will set "NBDKIT_CFLAGS" and "NBDKIT_LIBS" appropriately
1717       for compiling plugins.
1718
1719       You can also run pkg-config/pkgconf directly, for example:
1720
1721        if ! pkg-config nbdkit --exists; then
1722          echo "you must install the nbdkit plugin development environment"
1723          exit 1
1724        fi
1725
1726       You can also substitute the plugindir variable by doing:
1727
1728        PKG_CHECK_VAR([NBDKIT_PLUGINDIR], [nbdkit], [plugindir])
1729
1730       which defines "$(NBDKIT_PLUGINDIR)" in automake-generated Makefiles.
1731
1732       If nbdkit development headers are installed in a non-standard location
1733       then you may need to compile plugins using:
1734
1735        gcc -fPIC -shared myplugin.c -o myplugin.so \
1736          `pkg-config nbdkit --cflags --libs`
1737

INSTALLING THE PLUGIN

1739       The plugin is a "*.so" file and possibly a manual page.  You can of
1740       course install the plugin "*.so" file wherever you want, and users will
1741       be able to use it by running:
1742
1743        nbdkit /path/to/plugin.so [args]
1744
1745       However if the shared library has a name of the form
1746       "nbdkit-name-plugin.so" and if the library is installed in the
1747       $plugindir directory, then users can be run it by only typing:
1748
1749        nbdkit name [args]
1750
1751       The location of the $plugindir directory is set when nbdkit is compiled
1752       and can be found by doing:
1753
1754        nbdkit --dump-config
1755
1756       If using the pkg-config/pkgconf system then you can also find the
1757       plugin directory at compile time by doing:
1758
1759        pkg-config nbdkit --variable=plugindir
1760

WRITING PLUGINS IN C++

1762       Plugins in C++ work almost exactly like those in C, but the way you
1763       define the "nbdkit_plugin" struct is slightly different:
1764
1765        namespace {
1766          nbdkit_plugin create_plugin() {
1767            nbdkit_plugin plugin = nbdkit_plugin ();
1768            plugin.name     = "myplugin";
1769            plugin.open     = myplugin_open;
1770            plugin.get_size = myplugin_get_size;
1771            plugin.pread    = myplugin_pread;
1772            plugin.pwrite   = myplugin_pwrite;
1773            return plugin;
1774          }
1775        }
1776        static struct nbdkit_plugin plugin = create_plugin ();
1777        NBDKIT_REGISTER_PLUGIN(plugin)
1778

WRITING PLUGINS IN OTHER PROGRAMMING LANGUAGES

1780       You can also write nbdkit plugins in Go, Lua, OCaml, Perl, Python,
1781       Ruby, Rust, shell script or Tcl.  Other programming languages may be
1782       offered in future.
1783
1784       For more information see: nbdkit-cc-plugin(3), nbdkit-golang-plugin(3),
1785       nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3),
1786       nbdkit-python-plugin(3), nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3),
1787       nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .
1788
1789       Plugins written in scripting languages may also be installed in
1790       $plugindir.  These must be called "nbdkit-name-plugin" without any
1791       extension.  They must be executable, and they must use the shebang
1792       header (see "Shebang scripts" in nbdkit(1)).  For example a plugin
1793       written in Perl called "foo.pl" might be installed like this:
1794
1795        $ head -1 foo.pl
1796        #!/usr/sbin/nbdkit perl
1797
1798        $ sudo install -m 0755 foo.pl $plugindir/nbdkit-foo-plugin
1799
1800       and then users will be able to run it like this:
1801
1802        $ nbdkit foo [args ...]
1803

SEE ALSO

1805       nbdkit(1), nbdkit-nozero-filter(1), nbdkit-tls-fallback-filter(1),
1806       nbdkit-filter(3).
1807
1808       Standard plugins provided by nbdkit:
1809
1810       nbdkit-blkio-plugin(1), nbdkit-cdi-plugin(1), nbdkit-curl-plugin(1),
1811       nbdkit-data-plugin(1), nbdkit-eval-plugin(1),
1812       nbdkit-example1-plugin(1), nbdkit-example2-plugin(1),
1813       nbdkit-example3-plugin(1), nbdkit-example4-plugin(1),
1814       nbdkit-file-plugin(1), nbdkit-floppy-plugin(1), nbdkit-full-plugin(1),
1815       nbdkit-guestfs-plugin(1), nbdkit-info-plugin(1), nbdkit-iso-plugin(1),
1816       nbdkit-libvirt-plugin(1), nbdkit-linuxdisk-plugin(1),
1817       nbdkit-memory-plugin(1), nbdkit-nbd-plugin(1), nbdkit-null-plugin(1),
1818       nbdkit-ondemand-plugin(1), nbdkit-ones-plugin(1),
1819       nbdkit-partitioning-plugin(1), nbdkit-pattern-plugin(1),
1820       nbdkit-random-plugin(1), nbdkit-S3-plugin(1),
1821       nbdkit-sparse-random-plugin(1), nbdkit-split-plugin(1),
1822       nbdkit-ssh-plugin(1), nbdkit-tmpdisk-plugin(1),
1823       nbdkit-torrent-plugin(1), nbdkit-vddk-plugin(1), nbdkit-zero-plugin(1)
1824       ; nbdkit-cc-plugin(3), nbdkit-golang-plugin(3), nbdkit-lua-plugin(3),
1825       nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3), nbdkit-python-plugin(3),
1826       nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3), nbdkit-sh-plugin(3),
1827       nbdkit-tcl-plugin(3) .
1828

AUTHORS

1830       Eric Blake
1831
1832       Richard W.M. Jones
1833
1834       Pino Toscano
1835
1837       Copyright Red Hat
1838

LICENSE

1840       Redistribution and use in source and binary forms, with or without
1841       modification, are permitted provided that the following conditions are
1842       met:
1843
1844       •   Redistributions of source code must retain the above copyright
1845           notice, this list of conditions and the following disclaimer.
1846
1847       •   Redistributions in binary form must reproduce the above copyright
1848           notice, this list of conditions and the following disclaimer in the
1849           documentation and/or other materials provided with the
1850           distribution.
1851
1852       •   Neither the name of Red Hat nor the names of its contributors may
1853           be used to endorse or promote products derived from this software
1854           without specific prior written permission.
1855
1856       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
1857       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1858       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
1859       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
1860       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
1861       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
1862       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
1863       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
1864       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
1865       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
1866       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1867
1868
1869
1870nbdkit-1.36.2                     2023-11-26                  nbdkit-plugin(3)
Impressum