Provided by: nbdkit-plugin-dev_1.34.4-1ubuntu1_amd64 bug

NAME

       nbdkit-plugin - how to write nbdkit plugins

SYNOPSIS

        #define NBDKIT_API_VERSION 2
        #include <nbdkit-plugin.h>

        #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS

        static void *
        myplugin_open (void)
        {
          /* create a handle ... */
          return handle;
        }

        static struct nbdkit_plugin plugin = {
          .name              = "myplugin",
          .open              = myplugin_open,
          .get_size          = myplugin_get_size,
          .pread             = myplugin_pread,
          .pwrite            = myplugin_pwrite,
          /* etc */
        };
        NBDKIT_REGISTER_PLUGIN(plugin)

       Compile the plugin as a shared library:

        gcc -fPIC -shared myplugin.c -o myplugin.so

       and load it into nbdkit:

        nbdkit [--args ...] ./myplugin.so [key=value ...]

       When debugging, use the -fv options:

        nbdkit -fv ./myplugin.so [key=value ...]

DESCRIPTION

       An nbdkit plugin is a new source device which can be served using the Network Block Device
       (NBD) protocol.  This manual page describes how to create an nbdkit plugin in C.

       To see example plugins: https://gitlab.com/nbdkit/nbdkit/tree/master/plugins

       To write plugins in other languages, see: nbdkit-cc-plugin(3), nbdkit-golang-plugin(3),
       nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3),
       nbdkit-python-plugin(3), nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3),
       nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .

   API and ABI guarantee for C plugins
       Plugins written in C have an ABI guarantee: a plugin compiled against an older version of
       nbdkit will still work correctly when loaded with a newer nbdkit.  We also try (but cannot
       guarantee) to support plugins compiled against a newer version of nbdkit when loaded with
       an older nbdkit, although the plugin may have reduced functionality if it depends on
       features only provided by newer nbdkit.

       For plugins written in C, we also provide an API guarantee: a plugin written against an
       older header will still compile unmodified with a newer nbdkit.

       The API guarantee does not always apply to plugins written in other (non-C) languages
       which may have to adapt to changes when recompiled against a newer nbdkit.

WRITING AN NBDKIT PLUGIN

   "#define NBDKIT_API_VERSION 2"
       Plugins must choose which API version they want to use, by defining NBDKIT_API_VERSION
       before including "<nbdkit-plugin.h>" (or any other nbdkit header).

       If omitted, the default version is 1 for backwards-compatibility with nbdkit v1.1.26 and
       earlier; however, it is recommended that new plugins be written to the maximum version
       (currently 2) as it enables more features and better interaction with nbdkit filters.

       The rest of this document only covers the version 2 interface.  A newer nbdkit will always
       support plugins written in C which use any prior API version.

   "#include <nbdkit-plugin.h>"
       All plugins should start by including this header file (after optionally choosing an API
       version).

   "#define THREAD_MODEL ..."
       All plugins must define a thread model.  See "Threads" below for details.  It is generally
       safe to use:

        #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS

   "struct nbdkit_plugin"
       All plugins must define and register one "struct nbdkit_plugin", which contains the name
       of the plugin and pointers to callback functions, and use the
       "NBDKIT_REGISTER_PLUGIN(plugin)" macro:

        static struct nbdkit_plugin plugin = {
          .name              = "myplugin",
          .longname          = "My Plugin",
          .description       = "This is my great plugin for nbdkit",
          .open              = myplugin_open,
          .get_size          = myplugin_get_size,
          .pread             = myplugin_pread,
          .pwrite            = myplugin_pwrite,
          /* etc */
        };
        NBDKIT_REGISTER_PLUGIN(plugin)

       The ".name" field is the name of the plugin.

       The callbacks are described below (see "CALLBACKS").  Only ".name", ".open", ".get_size"
       and ".pread" are required.  All other callbacks can be omitted, although typical plugins
       need to use more.

   Callback lifecycle
       Callbacks are called in the following order over the lifecycle of the plugin:

                ┌──────────────────┐
                │ load             │
                └─────────┬────────┘
                          │           configuration phase starts     ─┐
                ┌─────────┴────────┐                                  ┆
                │ config           │  config is called once per       ┆
                └─────────┬────────┘↺ key=value on the command line   ┆
                ┌─────────┴────────┐                                  ┆
                │ config_complete  │                                  ┆
                └─────────┬────────┘                                  ┆
                ┌─────────┴────────┐                                  ┆
                │ thread_model     │                                  ┆
                └─────────┬────────┘  configuration phase ends       ─┘
                ┌─────────┴────────┐
                │ get_ready        │
                └─────────┬────────┘
                          │           nbdkit forks into the background
                ┌─────────┴────────┐
                │ after_fork       │
                └─────────┬────────┘
                          │           nbdkit starts serving clients
                          │
               ┌──────────┴─────────────┬─ ─ ─ ─ ─ ─ ─ ─ ─
        ┌──────┴─────┐ client #1        │
        │ preconnect │                  │
        └──────┬─────┘                  │
        ┌──────┴─────┐                  │
        │list_exports│                  │
        └──────┬─────┘                  │
        ┌──────┴─────┐                  │
        │ open       │                  │
        └──────┬─────┘                  │
        ┌──────┴─────┐  NBD option      │
        │ can_write  │  negotiation     │
        └──────┬─────┘                  │
        ┌──────┴─────┐           ┌──────┴─────┐ client #2
        │ get_size   │           │ preconnect │
        └──────┬─────┘           └──────┬─────┘
        ┌──────┴─────┐ data
        │ pread      │ serving
        └──────┬─────┘↺                ...
        ┌──────┴─────┐
        │ pwrite     │
        └──────┬─────┘↺          ┌──────┴─────┐
        ┌──────┴─────┐           │ close      │
        │ close      │           └────────────┘
        └────────────┘

                          │           before nbdkit exits
                          │
                ┌─────────┴────────┐
                │ cleanup          │
                └─────────┬────────┘
                ┌─────────┴────────┐
                │ unload           │
                └──────────────────┘

       Notes

       "nbdkit --dump-plugin"
           The order of calls when the user queries the plugin is slightly different: ".config"
           is called once for each parameter.  ".config_complete" is not called.  ".thread_model"
           is called after ".config".

       ".get_ready"
           This is the last chance to do any global preparation that is needed to serve
           connections.  In particular, error messages here will be visible to the user, but they
           might not be in ".after_fork" (see below).

           Plugins should not create background threads here.  Use ".after_fork" instead.

       ".after_fork"
           ".after_fork" is called after the server has forked into the background and changed
           UID and directory.  If a plugin needs to create background threads (or uses an
           external library that creates threads) it should do so here, because background
           threads are invalidated by fork.

           Because the server may have forked into the background, error messages and failures
           from ".after_fork" cannot be seen by the user unless they look through syslog.  An
           error in ".after_fork" can appear to the user as if nbdkit “just died”.  So in almost
           all cases it is better to use ".get_ready" instead of this callback, or to do as much
           preparation work as possible in ".get_ready" and only start background threads here.

           The server doesn't always fork (eg. if the -f flag is used), but even so this callback
           will be called.  If you want to find out if the server forked between ".get_ready" and
           ".after_fork" use getpid(2).

       ".preconnect" and ".open"
           ".preconnect" is called when a TCP connection has been made to the server.  This
           happens early, before NBD or TLS negotiation.

           ".open" is called when a new client has connected and finished the NBD handshake.  TLS
           negotiation (if used) has been completed successfully.

       ".can_write", ".get_size" and other option negotiation callbacks
           These are called during option negotiation with the client, but before any data is
           served.  These callbacks may return different values across different ".open" calls,
           but within a single connection, they are called at most once and cached by nbdkit for
           that connection.

       ".pread", ".pwrite" and other data serving callbacks
           After option negotiation has finished, these may be called to serve data.  Depending
           on the thread model chosen, they might be called in parallel from multiple threads.
           The data serving callbacks include a flags argument; the results of the negotiation
           callbacks influence whether particular flags will ever be passed to a data callback.

       ".cleanup" and ".unload"
           The difference between these two methods is that ".cleanup" is called before any
           filter has been removed from memory with dlclose(3).  When ".unload" is called, nbdkit
           is in the middle of calling dlclose(3).  Most plugins do not need to worry about this
           difference.

   Flags
       The following flags are defined by nbdkit, and used in various data serving callbacks as
       follows:

       "NBDKIT_FLAG_MAY_TRIM"
           This flag is used by the ".zero" callback; there is no way to disable this flag,
           although a plugin that does not support trims as a way to write zeroes may ignore the
           flag without violating expected semantics.

       "NBDKIT_FLAG_FUA"
           This flag represents Forced Unit Access semantics.  It is used by the ".pwrite",
           ".zero", and ".trim" callbacks to indicate that the plugin must not return a result
           until the action has landed in persistent storage.  This flag will not be sent to the
           plugin unless ".can_fua" is provided and returns "NBDKIT_FUA_NATIVE".

       The following defines are valid as successful return values for ".can_fua":

       "NBDKIT_FUA_NONE"
           Forced Unit Access is not supported; the client must manually request a flush after
           writes have completed.  The "NBDKIT_FLAG_FUA" flag will not be passed to the plugin's
           write callbacks.

       "NBDKIT_FUA_EMULATE"
           The client may request Forced Unit Access, but it is implemented by emulation, where
           nbdkit calls ".flush" after a write operation; this is semantically correct, but may
           hurt performance as it tends to flush more data than just what the client requested.
           The "NBDKIT_FLAG_FUA" flag will not be passed to the plugin's write callbacks.

       "NBDKIT_FUA_NATIVE"
           The client may request Forced Unit Access, which results in the "NBDKIT_FLAG_FUA" flag
           being passed to the plugin's write callbacks (".pwrite", ".trim", and ".zero").  When
           the flag is set, these callbacks must not return success until the client's request
           has landed in persistent storage.

       The following defines are valid as successful return values for ".can_cache":

       "NBDKIT_CACHE_NONE"
           The server does not advertise caching support, and rejects any client-requested
           caching. Any ".cache" callback is ignored.

       "NBDKIT_CACHE_EMULATE"
           The nbdkit server advertises cache support to the client, where the client may request
           that the server cache a region of the export to potentially speed up future read
           and/or write operations on that region. The nbdkit server implements the caching by
           calling ".pread" and ignoring the results. This option exists to ease the
           implementation of a common form of caching; any ".cache" callback is ignored.

       "NBDKIT_CACHE_NATIVE"
           The nbdkit server advertises cache support to the client, where the client may request
           that the server cache a region of the export to potentially speed up future read
           and/or write operations on that region. The nbdkit server calls the ".cache" callback
           to perform the caching; if that callback is missing, the client's cache request
           succeeds without doing anything.

   Threads
       Each nbdkit plugin must declare its maximum thread safety model by defining the
       "THREAD_MODEL" macro.  (This macro is used by "NBDKIT_REGISTER_PLUGIN").  Additionally, a
       plugin may implement the ".thread_model" callback, called right after ".config_complete"
       to make a runtime decision on which thread model to use.  The nbdkit server chooses the
       most restrictive model between the plugin's "THREAD_MODEL", the ".thread_model" if
       present, any restrictions requested by filters, and any limitations imposed by the
       operating system.

       In "nbdkit --dump-plugin PLUGIN" output, the "max_thread_model" line matches the
       "THREAD_MODEL" macro, and the "thread_model" line matches what the system finally settled
       on after applying all restrictions.

       The possible settings for "THREAD_MODEL" are defined below.

       "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_CONNECTIONS"
           Only a single handle can be open at any time, and all requests happen from one thread.

           Note this means only one client can connect to the server at any time.  If a second
           client tries to connect it will block waiting for the first client to close the
           connection.

       "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS"
           This is a safe default for most plugins.

           Multiple handles can be open at the same time, but requests are serialized so that for
           the plugin as a whole only one open/read/write/close (etc) request will be in progress
           at any time.

           This is a useful setting if the library you are using is not thread-safe.  However
           performance may not be good.

       "#define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_REQUESTS"
           Multiple handles can be open and multiple data requests can happen in parallel.
           However only one request will happen per handle at a time (but requests on different
           handles might happen concurrently).

       "#define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL"
           Multiple handles can be open and multiple data requests can happen in parallel (even
           on the same handle).  The server may reorder replies, answering a later request before
           an earlier one.

           All the libraries you use must be thread-safe and reentrant, and any code that creates
           a file descriptor should atomically set "FD_CLOEXEC" if you do not want it
           accidentally leaked to another thread's child process.  You may also need to provide
           mutexes for fields in your connection handle.

       If none of the above thread models are suitable, use "NBDKIT_THREAD_MODEL_PARALLEL" and
       implement your own locking using "pthread_mutex_t" etc.

   Error handling
       If there is an error in the plugin, the plugin should call "nbdkit_error" to report an
       error message; additionally, if the callback is involved in serving data, the plugin
       should call "nbdkit_set_error" to influence the error code that will be sent to the
       client.  These two functions can be called in either order.  Then, the callback should
       return the appropriate error indication, eg. "NULL" or "-1".

       If the call to "nbdkit_set_error" is omitted while serving data, then the global variable
       "errno" may be used.  For plugins which have ".errno_is_preserved != 0" the core code will
       use "errno".  In plugins written in non-C languages, we usually cannot trust that "errno"
       will not be overwritten when returning from that language to C.  In that case, either the
       plugin must call "nbdkit_set_error" or hard-coded "EIO" is used.

       "nbdkit_error" has the following prototype and works like printf(3):

        void nbdkit_error (const char *fs, ...);
        void nbdkit_verror (const char *fs, va_list args);

       For convenience, "nbdkit_error" preserves the value of "errno", and also supports the
       glibc extension of a single %m in a format string expanding to "strerror(errno)", even on
       platforms that don't support that natively.

       "nbdkit_set_error" can be called at any time, but only has an impact during callbacks for
       serving data, and only when the callback returns an indication of failure.  It has the
       following prototype:

        void nbdkit_set_error (int err);

CALLBACKS

   ".name"
        const char *name;

       This field (a string) is required, and must contain only ASCII alphanumeric characters or
       non-leading dashes, and be unique amongst all plugins.

   ".version"
        const char *version;

       Plugins may optionally set a version string which is displayed in help and debugging
       output.  (See also "VERSION" below)

   ".longname"
        const char *longname;

       An optional free text name of the plugin.  This field is used in error messages.

   ".description"
        const char *description;

       An optional multi-line description of the plugin.

   ".load"
        void load (void);

       This is called once just after the plugin is loaded into memory.  You can use this to
       perform any global initialization needed by the plugin.

   ".unload"
        void unload (void);

       This may be called once just before the plugin is unloaded from memory.  Note that it's
       not guaranteed that ".unload" will always be called (eg. the server might be killed or
       segfault), so you should try to make the plugin as robust as possible by not requiring
       cleanup.  See also "SHUTDOWN" below.

   ".dump_plugin"
        void dump_plugin (void);

       This optional callback is called when the "nbdkit plugin --dump-plugin" command is used.
       It should print any additional informative "key=value" fields to stdout as needed.
       Prefixing the keys with the name of the plugin will avoid conflicts.

   ".config"
        int config (const char *key, const char *value);

       On the nbdkit command line, after the plugin filename, come an optional list of
       "key=value" arguments.  These are passed to the plugin through this callback when the
       plugin is first loaded and before any connections are accepted.

       This callback may be called zero or more times.

       Both "key" and "value" parameters will be non-NULL.  The strings are owned by nbdkit but
       will remain valid for the lifetime of the plugin, so the plugin does not need to copy
       them.

       The key will be a non-empty string beginning with an ASCII alphabetic character ("A-Z"
       "a-z").  The rest of the key must contain only ASCII alphanumeric plus period, underscore
       or dash characters ("A-Z" "a-z" "0-9" "." "_" "-").  The value may be an arbitrary string,
       including an empty string.

       The names of "key"s accepted by plugins is up to the plugin, but you should probably look
       at other plugins and follow the same conventions.

       If the value is a relative path, then note that the server changes directory when it
       starts up.  See "FILENAMES AND PATHS" above.

       If "nbdkit_stdio_safe" returns 1, the value of the configuration parameter may be used to
       trigger reading additional data through stdin (such as a password or inline script).

       If the ".config" callback is not provided by the plugin, and the user tries to specify any
       "key=value" arguments, then nbdkit will exit with an error.

       If there is an error, ".config" should call "nbdkit_error" with an error message and
       return "-1".

   ".magic_config_key"
        const char *magic_config_key;

       This optional string can be used to set a "magic" key used when parsing plugin parameters.
       It affects how "bare parameters" (those which do not contain an "=" character) are parsed
       on the command line.

       If "magic_config_key != NULL" then any bare parameters are passed to the ".config" method
       as: "config (magic_config_key, argv[i]);".

       If "magic_config_key" is not set then we behave as in nbdkit < 1.7: If the first parameter
       on the command line is bare then it is passed to the ".config" method as:
       "config ("script", value);".  Any other bare parameters give errors.

   ".config_complete"
        int config_complete (void);

       This optional callback is called after all the configuration has been passed to the
       plugin.  It is a good place to do checks, for example that the user has passed the
       required parameters to the plugin.

       If there is an error, ".config_complete" should call "nbdkit_error" with an error message
       and return "-1".

   ".config_help"
        const char *config_help;

       This optional multi-line help message should summarize any "key=value" parameters that it
       takes.  It does not need to repeat what already appears in ".description".

       If the plugin doesn't take any config parameters you should probably omit this.

   ".thread_model"
        int thread_model (void)

       This optional callback is called after all the configuration has been passed to the
       plugin.  It can be used to force a stricter thread model based on configuration, compared
       to "THREAD_MODEL".  See "Threads" above for details.  Attempts to request a looser (more
       parallel) model are silently ignored.

       If there is an error, ".thread_model" should call "nbdkit_error" with an error message and
       return "-1".

   ".get_ready"
        int get_ready (void);

       This optional callback is called before the server starts serving.  It is called before
       the server forks or changes directory.  It is ordinarily the last chance to do any global
       preparation that is needed to serve connections.

       If there is an error, ".get_ready" should call "nbdkit_error" with an error message and
       return "-1".

   ".after_fork"
        int after_fork (void);

       This optional callback is called before the server starts serving.  It is called after the
       server forks and changes directory.  If a plugin needs to create background threads (or
       uses an external library that creates threads) it should do so here, because background
       threads are killed by fork.  However you should try to do as little as possible here
       because error reporting is difficult.  See "Callback lifecycle" above.

       If there is an error, ".after_fork" should call "nbdkit_error" with an error message and
       return "-1".

   ".cleanup"
        void cleanup (void);

       This optional callback is called after the server has closed all connections and is
       preparing to unload.  It is only reached in the same cases that the ".after_fork" callback
       was used, making it a good place to clean up any background threads.  However, it is not
       guaranteed that this callback will be reached, so you should try to make the plugin as
       robust as possible by not requiring cleanup.  See also "SHUTDOWN" below.

   ".preconnect"
        int preconnect (int readonly);

       This optional callback is called when a TCP connection has been made to the server.  This
       happens early, before NBD or TLS negotiation.  If TLS authentication is required to access
       the server, then it has not been negotiated at this point.

       For security reasons (to avoid denial of service attacks) this callback should be written
       to be as fast and take as few resources as possible.  If you use this callback, only use
       it to do basic access control, such as checking "nbdkit_peer_name", "nbdkit_peer_pid",
       "nbdkit_peer_uid", "nbdkit_peer_gid" against a list of permitted source addresses (see
       "PEER NAME" and nbdkit-ip-filter(1)).  It may be better to do access control outside the
       server, for example using TCP wrappers or a firewall.

       The "readonly" flag informs the plugin that the server was started with the -r flag on the
       command line.

       Returning 0 will allow the connection to continue.  If there is an error or you want to
       deny the connection, call "nbdkit_error" with an error message and return "-1".

   ".list_exports"
        int list_exports (int readonly, int is_tls,
                          struct nbdkit_exports *exports);

       This optional callback is called if the client tries to list the exports served by the
       plugin (using "NBD_OPT_LIST").  If the plugin does not supply this callback then the
       result of ".default_export" is advertised as the lone export.  The NBD protocol defines ""
       as the default export, so this is suitable for plugins which ignore the export name and
       always serve the same content.  See also "EXPORT NAME" below.

       The "readonly" flag informs the plugin that the server was started with the -r flag on the
       command line, which is the same value passed to ".preconnect" and ".open".  However, the
       NBD protocol does not yet have a way to let the client advertise an intent to be read-only
       even when the server allows writes, so this parameter may not be as useful as it appears.

       The "is_tls" flag informs the plugin whether this listing was requested after the client
       has completed TLS negotiation.  When running the server in a mode that permits but does
       not require TLS, be careful that any exports listed when "is_tls" is "false" do not leak
       unintended information.

       The "exports" parameter is an opaque object for collecting the list of exports.  Call
       "nbdkit_add_export" as needed to add specific exports to the list.

        int nbdkit_add_export (struct nbdkit_export *exports,
                               const char *name, const char *description);

       The "name" must be a non-NULL, UTF-8 string between 0 and 4096 bytes in length.  Export
       names must be unique.  "description" is an optional description of the export which some
       clients can display but which is otherwise unused (if you don't want a description, you
       can pass this parameter as "NULL").  The string(s) are copied into the exports list so you
       may free them immediately after calling this function.  "nbdkit_add_export" returns 0 on
       success or "-1" on failure; on failure "nbdkit_error" has already been called, with
       "errno" set to a suitable value.

       There are also situations where a plugin may wish to duplicate the nbdkit default behavior
       of supplying an export list containing only the result of ".default_export" when
       ".list_exports" is missing; this is most common in a language binding where it is not
       known at compile time whether the language script will be providing an implementation for
       ".list_exports", and is done by calling "nbdkit_use_default_export".

        int nbdkit_use_default_export (struct nbdkit_export *exports);

       "nbdkit_use_default_export" returns 0 on success or "-1" on failure; on failure
       "nbdkit_error" has already been called, with "errno" set to a suitable value.

       The plugin may also leave the export list empty, by not calling either helper.  Once the
       plugin is happy with the list contents, returning 0 will send the list of exports back to
       the client.  If there is an error, ".list_exports" should call "nbdkit_error" with an
       error message and return "-1".

   ".default_export"
        const char *default_export (int readonly, int is_tls);

       This optional callback is called if the client tries to connect to the default export "",
       where the plugin provides a UTF-8 string between 0 and 4096 bytes.  If the plugin does not
       supply this callback, the connection continues with the empty name; if the plugin returns
       a valid string, nbdkit behaves as if the client had passed that string instead of an empty
       name, and returns that name to clients that support it (see the "NBD_INFO_NAME" response
       to "NBD_OPT_GO").  Similarly, if the plugin does not supply a ".list_exports" callback,
       the result of this callback determines what export name to advertise to a client
       requesting an export list.

       The "readonly" flag informs the plugin that the server was started with the -r flag on the
       command line, which is the same value passed to ".preconnect" and ".open".  However, the
       NBD protocol does not yet have a way to let the client advertise an intent to be read-only
       even when the server allows writes, so this parameter may not be as useful as it appears.

       The "is_tls" flag informs the plugin whether the canonical name for the default export is
       being requested after the client has completed TLS negotiation.  When running the server
       in a mode that permits but does not require TLS, be careful that a default export name
       does not leak unintended information.

       If the plugin returns "NULL" or an invalid string (such as longer than 4096 bytes), the
       client is not permitted to connect to the default export.  However, this is not an error
       in the protocol, so it is not necessary to call "nbdkit_error".

   ".open"
        void *open (int readonly);

       This is called when a new client connects to the nbdkit server.  The callback should
       allocate a handle and return it.  This handle is passed back to other callbacks and could
       be freed in the ".close" callback.

       Note that the handle is completely opaque to nbdkit, but it must not be NULL.  If you
       don't need to use a handle, return "NBDKIT_HANDLE_NOT_NEEDED" which is a static non-NULL
       pointer.

       The "readonly" flag informs the plugin that the server was started with the -r flag on the
       command line which forces connections to be read-only.  Note that the plugin may
       additionally force the connection to be readonly (even if this flag is false) by returning
       false from the ".can_write" callback.  So if your plugin can only serve read-only, you can
       ignore this parameter.

       If the plugin wants to differentiate the content it serves based on client input, then
       this is the spot to use "nbdkit_export_name()" to determine which export the client
       requested.  See also "EXPORT NAME" below.

       This callback is called after the NBD handshake has completed; if the server requires TLS
       authentication, then that has occurred as well.  But if the server is set up to have
       optional TLS authentication, you may check "nbdkit_is_tls" to learn whether the client has
       completed TLS authentication.  When running the server in a mode that permits but does not
       require TLS, be careful that you do not allow unauthenticated clients to cause a denial of
       service against authentication.

       If there is an error, ".open" should call "nbdkit_error" with an error message and return
       "NULL".

   ".close"
        void close (void *handle);

       This is called when the client closes the connection.  It should clean up any per-
       connection resources.

       Note there is no way in the NBD protocol to communicate close errors back to the client,
       for example if your plugin calls close(2) and you are checking for errors (as you should
       do).  Therefore the best you can do is to log the error on the server.  Well-behaved NBD
       clients should try to flush the connection before it is closed and check for errors, but
       obviously this is outside the scope of nbdkit.

   ".get_size"
        int64_t get_size (void *handle);

       This is called during the option negotiation phase of the protocol to get the size (in
       bytes) of the block device being exported.

       The returned size must be ≥ 0.  If there is an error, ".get_size" should call
       "nbdkit_error" with an error message and return "-1".

   ".export_description"
        const char *export_description (void *handle);

       This is called during the option negotiation phase only if the client specifically
       requested an export description (see the "NBD_INFO_DESCRIPTION" response to "NBD_OPT_GO").
       Any description provided must be human-readable UTF-8, no longer than 4096 bytes.
       Ideally, this description should match any description set during ".list_exports", but
       that is not enforced.

       If the plugin returns "NULL" or an invalid string (such as longer than 4096 bytes), or if
       this callback is omitted, no description is offered to the client.  As this is not an
       error in the protocol, it is not necessary to call "nbdkit_error".  If the callback will
       not be returning a compile-time constant string, you may find "nbdkit_strdup_intern"
       helpful for returning a value that avoids a memory leak.

   ".block_size"
        int block_size (void *handle, uint32_t *minimum,
                        uint32_t *preferred, uint32_t *maximum);

       This is called during the option negotiation phase of the protocol to get the minimum,
       preferred and maximum block size (all in bytes) of the block device.  The client should
       obey these constraints by not making requests which are smaller than the minimum size or
       larger than the maximum size, and usually making requests of a multiple of the preferred
       size.  Furthermore requests should be aligned to at least the minimum block size, and
       usually the preferred block size.

       "Preferred" block size in the NBD specification can be misinterpreted.  It means the I/O
       size which does not have a penalty for read-modify-write.

       Even if the plugin implements this callback, this does not mean that all client requests
       will obey the constraints.  A client could still ignore the constraints.  nbdkit passes
       all requests through to the plugin, because what the plugin does depends on the plugin's
       policy.  It might decide to serve the requests correctly anyway, or reject them with an
       error.  Plugins can avoid this complexity by using nbdkit-blocksize-policy-filter(1) which
       allows both setting/adjusting the constraints, and selecting an error policy.

       The minimum block size must be ≥ 1.  The maximum block size must be ≤ 0xffff_ffff.
       minimum ≤ preferred ≤ maximum.

       As a special case, the plugin may return minimum == preferred == maximum == 0, meaning no
       information.

       If this callback is not used, then the NBD protocol assumes by default minimum = 1,
       preferred = 4096.  (Maximum block size depends on various factors, see the NBD protocol
       specification, section "Block size constraints").

   ".can_write"
        int can_write (void *handle);

       This is called during the option negotiation phase to find out if the handle supports
       writes.

       If there is an error, ".can_write" should call "nbdkit_error" with an error message and
       return "-1".

       This callback is not required.  If omitted, then we return true iff a ".pwrite" callback
       has been defined.

   ".can_flush"
        int can_flush (void *handle);

       This is called during the option negotiation phase to find out if the handle supports the
       flush-to-disk operation.

       If there is an error, ".can_flush" should call "nbdkit_error" with an error message and
       return "-1".

       This callback is not required.  If omitted, then we return true iff a ".flush" callback
       has been defined.

   ".is_rotational"
        int is_rotational (void *handle);

       This is called during the option negotiation phase to find out if the backing disk is a
       rotational medium (like a traditional hard disk) or not (like an SSD).  If true, this may
       cause the client to reorder requests to make them more efficient for a slow rotating disk.

       If there is an error, ".is_rotational" should call "nbdkit_error" with an error message
       and return "-1".

       This callback is not required.  If omitted, then we return false.

   ".can_trim"
        int can_trim (void *handle);

       This is called during the option negotiation phase to find out if the plugin supports the
       trim/discard operation for punching holes in the backing storage.

       If there is an error, ".can_trim" should call "nbdkit_error" with an error message and
       return "-1".

       This callback is not required.  If omitted, then we return true iff a ".trim" callback has
       been defined.

   ".can_zero"
        int can_zero (void *handle);

       This is called during the option negotiation phase to find out if the plugin wants the
       ".zero" callback to be utilized.  Support for writing zeroes is still advertised to the
       client (unless the nbdkit-nozero-filter(1) is also used), so returning false merely serves
       as a way to avoid complicating the ".zero" callback to have to fail with "ENOTSUP" or
       "EOPNOTSUPP" on the connections where it will never be more efficient than using ".pwrite"
       up front.

       If there is an error, ".can_zero" should call "nbdkit_error" with an error message and
       return "-1".

       This callback is not required.  If omitted, then for a normal zero request, nbdkit always
       tries ".zero" first if it is present, and gracefully falls back to ".pwrite" if ".zero"
       was absent or failed with "ENOTSUP" or "EOPNOTSUPP".

   ".can_fast_zero"
        int can_fast_zero (void *handle);

       This is called during the option negotiation phase to find out if the plugin wants to
       advertise support for fast zero requests.  If this support is not advertised, a client
       cannot attempt fast zero requests, and has no way to tell if writing zeroes offers any
       speedups compared to using ".pwrite" (other than compressed network traffic).  If support
       is advertised, then ".zero" will have "NBDKIT_FLAG_FAST_ZERO" set when the client has
       requested a fast zero, in which case the plugin must fail with "ENOTSUP" or "EOPNOTSUPP"
       up front if the request would not offer any benefits over ".pwrite".  Advertising support
       for fast zero requests does not require that writing zeroes be fast, only that the result
       (whether success or failure) is fast, so this should be advertised when feasible.

       If there is an error, ".can_fast_zero" should call "nbdkit_error" with an error message
       and return "-1".

       This callback is not required.  If omitted, then nbdkit returns true if ".zero" is absent
       or ".can_zero" returns false (in those cases, nbdkit fails all fast zero requests, as its
       fallback to ".pwrite" is not inherently faster), otherwise false (since it cannot be
       determined in advance if the plugin's ".zero" will properly honor the semantics of
       "NBDKIT_FLAG_FAST_ZERO").

   ".can_extents"
        int can_extents (void *handle);

       This is called during the option negotiation phase to find out if the plugin supports
       detecting allocated (non-sparse) regions of the disk with the ".extents" callback.

       If there is an error, ".can_extents" should call "nbdkit_error" with an error message and
       return "-1".

       This callback is not required.  If omitted, then we return true iff a ".extents" callback
       has been defined.

   ".can_fua"
        int can_fua (void *handle);

       This is called during the option negotiation phase to find out if the plugin supports the
       Forced Unit Access (FUA) flag on write, zero, and trim requests.  If this returns
       "NBDKIT_FUA_NONE", FUA support is not advertised to the client; if this returns
       "NBDKIT_FUA_EMULATE", the ".flush" callback must work (even if ".can_flush" returns
       false), and FUA support is emulated by calling ".flush" after any write operation; if this
       returns "NBDKIT_FUA_NATIVE", then the ".pwrite", ".zero", and ".trim" callbacks (if
       implemented) must handle the flag "NBDKIT_FLAG_FUA", by not returning until that action
       has landed in persistent storage.

       If there is an error, ".can_fua" should call "nbdkit_error" with an error message and
       return "-1".

       This callback is not required unless a plugin wants to specifically handle FUA requests.
       If omitted, nbdkit checks whether ".flush" exists, and behaves as if this function returns
       "NBDKIT_FUA_NONE" or "NBDKIT_FUA_EMULATE" as appropriate.

   ".can_multi_conn"
        int can_multi_conn (void *handle);

       This is called during the option negotiation phase to find out if the plugin is prepared
       to handle multiple connections from a single client.  If the plugin sets this to true then
       a client may try to open multiple connections to the nbdkit server and spread requests
       across all connections to maximize parallelism.  If the plugin sets it to false (which is
       the default) then well-behaved clients should only open a single connection, although we
       cannot control what clients do in practice.

       Specifically it means that either the plugin does not cache requests at all.  Or if it
       does cache them then the effects of a ".flush" request or setting "NBDKIT_FLAG_FUA" on a
       request must be visible across all connections to the plugin before the plugin replies to
       that request.

       Properly working clients should send the same export name for each of these connections.

       If you use Linux nbd-client(8) option -C num with num > 1 then Linux checks this flag and
       will refuse to connect if ".can_multi_conn" is false.

       If there is an error, ".can_multi_conn" should call "nbdkit_error" with an error message
       and return "-1".

       This callback is not required.  If omitted, then we return false.

   ".can_cache"
        int can_cache (void *handle);

       This is called during the option negotiation phase to find out if the plugin supports a
       cache or prefetch operation.

       This can return:

       "NBDKIT_CACHE_NONE"
           Cache support is not advertised to the client.

       "NBDKIT_CACHE_EMULATE"
           Caching is emulated by the server calling ".pread" and discarding the result.

       "NBDKIT_CACHE_NATIVE"
           Cache support is advertised to the client.  The ".cache" callback will be called if it
           exists, otherwise all cache requests instantly succeed.

       If there is an error, ".can_cache" should call "nbdkit_error" with an error message and
       return "-1".

       This callback is not required.  If omitted, then we return "NBDKIT_CACHE_NONE" if the
       ".cache" callback is missing, or "NBDKIT_CACHE_NATIVE" if it is defined.

   ".pread"
        int pread (void *handle, void *buf, uint32_t count, uint64_t offset,
                   uint32_t flags);

       During the data serving phase, nbdkit calls this callback to read data from the backing
       store.  "count" bytes starting at "offset" in the backing store should be read and copied
       into "buf".  nbdkit takes care of all bounds- and sanity-checking, so the plugin does not
       need to worry about that.

       The parameter "flags" exists in case of future NBD protocol extensions; at this time, it
       will be 0 on input.

       The callback must read the whole "count" bytes if it can.  The NBD protocol doesn't allow
       partial reads (instead, these would be errors).  If the whole "count" bytes was read, the
       callback should return 0 to indicate there was no error.

       If there is an error (including a short read which couldn't be recovered from), ".pread"
       should call "nbdkit_error" with an error message, and "nbdkit_set_error" to record an
       appropriate error (unless "errno" is sufficient), then return "-1".

   ".pwrite"
        int pwrite (void *handle, const void *buf, uint32_t count, uint64_t offset,
                    uint32_t flags);

       During the data serving phase, nbdkit calls this callback to write data to the backing
       store.  "count" bytes starting at "offset" in the backing store should be written using
       the data in "buf".  nbdkit takes care of all bounds- and sanity-checking, so the plugin
       does not need to worry about that.

       This function will not be called if ".can_write" returned false.  The parameter "flags"
       may include "NBDKIT_FLAG_FUA" on input based on the result of ".can_fua".

       The callback must write the whole "count" bytes if it can.  The NBD protocol doesn't allow
       partial writes (instead, these would be errors).  If the whole "count" bytes was written
       successfully, the callback should return 0 to indicate there was no error.

       If there is an error (including a short write which couldn't be recovered from), ".pwrite"
       should call "nbdkit_error" with an error message, and "nbdkit_set_error" to record an
       appropriate error (unless "errno" is sufficient), then return "-1".

   ".flush"
        int flush (void *handle, uint32_t flags);

       During the data serving phase, this callback is used to fdatasync(2) the backing store,
       ie. to ensure it has been completely written to a permanent medium.  If that is not
       possible then you can omit this callback.

       This function will not be called directly by the client if ".can_flush" returned false;
       however, it may still be called by nbdkit if ".can_fua" returned "NBDKIT_FUA_EMULATE".
       The parameter "flags" exists in case of future NBD protocol extensions; at this time, it
       will be 0 on input.

       If there is an error, ".flush" should call "nbdkit_error" with an error message, and
       "nbdkit_set_error" to record an appropriate error (unless "errno" is sufficient), then
       return "-1".

   ".trim"
        int trim (void *handle, uint32_t count, uint64_t offset, uint32_t flags);

       During the data serving phase, this callback is used to "punch holes" in the backing
       store.  If that is not possible then you can omit this callback.

       This function will not be called if ".can_trim" returned false.  The parameter "flags" may
       include "NBDKIT_FLAG_FUA" on input based on the result of ".can_fua".

       If there is an error, ".trim" should call "nbdkit_error" with an error message, and
       "nbdkit_set_error" to record an appropriate error (unless "errno" is sufficient), then
       return "-1".

   ".zero"
        int zero (void *handle, uint32_t count, uint64_t offset, uint32_t flags);

       During the data serving phase, this callback is used to write "count" bytes of zeroes at
       "offset" in the backing store.

       This function will not be called if ".can_zero" returned false.  On input, the parameter
       "flags" may include "NBDKIT_FLAG_MAY_TRIM" unconditionally, "NBDKIT_FLAG_FUA" based on the
       result of ".can_fua", and "NBDKIT_FLAG_FAST_ZERO" based on the result of ".can_fast_zero".

       If "NBDKIT_FLAG_MAY_TRIM" is requested, the operation can punch a hole instead of writing
       actual zero bytes, but only if subsequent reads from the hole read as zeroes.

       If "NBDKIT_FLAG_FAST_ZERO" is requested, the plugin must decide up front if the
       implementation is likely to be faster than a corresponding ".pwrite"; if not, then it must
       immediately fail with "ENOTSUP" or "EOPNOTSUPP" (whether by "nbdkit_set_error" or "errno")
       and preferably without modifying the exported image.  It is acceptable to always fail a
       fast zero request (as a fast failure is better than attempting the write only to find out
       after the fact that it was not fast after all).  Note that on Linux, support for
       "ioctl(BLKZEROOUT)" is insufficient for determining whether a zero request to a block
       device will be fast (because the kernel will perform a slow fallback when needed).

       The callback must write the whole "count" bytes if it can.  The NBD protocol doesn't allow
       partial writes (instead, these would be errors).  If the whole "count" bytes was written
       successfully, the callback should return 0 to indicate there was no error.

       If there is an error, ".zero" should call "nbdkit_error" with an error message, and
       "nbdkit_set_error" to record an appropriate error (unless "errno" is sufficient), then
       return "-1".

       If this callback is omitted, or if it fails with "ENOTSUP" or "EOPNOTSUPP" (whether by
       "nbdkit_set_error" or "errno"), then ".pwrite" will be used as an automatic fallback
       except when the client requested a fast zero.

   ".extents"
        int extents (void *handle, uint32_t count, uint64_t offset,
                     uint32_t flags, struct nbdkit_extents *extents);

       During the data serving phase, this callback is used to detect allocated, sparse and
       zeroed regions of the disk.

       This function will not be called if ".can_extents" returned false.  nbdkit's default
       behaviour in this case is to treat the whole virtual disk as if it was allocated.  Also,
       this function will not be called by a client that does not request structured replies (the
       --no-sr option of nbdkit can be used to test behavior when ".extents" is unavailable to
       the client).

       The callback should detect and return the list of extents overlapping the range
       "[offset...offset+count-1]".  The "extents" parameter points to an opaque object which the
       callback should fill in by calling "nbdkit_add_extent".  See "Extents list" below.

       If there is an error, ".extents" should call "nbdkit_error" with an error message, and
       "nbdkit_set_error" to record an appropriate error (unless "errno" is sufficient), then
       return "-1".

       Extents list

       The plugin "extents" callback is passed an opaque pointer "struct nbdkit_extents
       *extents".  This structure represents a list of filesystem extents describing which areas
       of the disk are allocated, which are sparse (“holes”), and, if supported, which are
       zeroes.

       The "extents" callback should scan the disk starting at "offset" and call
       "nbdkit_add_extent" for each extent found.

       Extents overlapping the range "[offset...offset+count-1]" should be returned if possible.
       However nbdkit ignores extents < offset so the plugin may, if it is easier to implement,
       return all extent information for the whole disk.  The plugin may return extents beyond
       the end of the range.  It may also return extent information for less than the whole
       range, but it must return at least one extent overlapping "offset".

       The extents must be added in ascending order, and must be contiguous.

       The "flags" parameter of the ".extents" callback may contain the flag
       "NBDKIT_FLAG_REQ_ONE".  This means that the client is only requesting information about
       the extent overlapping "offset".  The plugin may ignore this flag, or as an optimization
       it may return just a single extent for "offset".

        int nbdkit_add_extent (struct nbdkit_extents *extents,
                               uint64_t offset, uint64_t length, uint32_t type);

       Add an extent covering "[offset...offset+length-1]" of one of the following four types:

       "type = 0"
           A normal, allocated data extent.

       "type = NBDKIT_EXTENT_HOLE|NBDKIT_EXTENT_ZERO"
           An unallocated extent, a.k.a. a “hole”, which reads back as zeroes.  This is the
           normal type of hole applicable to most disks.

       "type = NBDKIT_EXTENT_ZERO"
           An allocated extent which is known to contain only zeroes.

       "type = NBDKIT_EXTENT_HOLE"
           An unallocated extent (hole) which does not read back as zeroes.  Note this should
           only be used in specialized circumstances such as when writing a plugin for (or to
           emulate) certain SCSI drives which do not guarantee that trimmed blocks read back as
           zeroes.

       "nbdkit_add_extent" returns 0 on success or "-1" on failure.  On failure "nbdkit_error"
       and/or "nbdkit_set_error" has already been called.  "errno" will be set to a suitable
       value.

   ".cache"
        int cache (void *handle, uint32_t count, uint64_t offset, uint32_t flags);

       During the data serving phase, this callback is used to give the plugin a hint that the
       client intends to make further accesses to the given region of the export.

       The nature of caching/prefetching is not specified further by the NBD specification.  For
       example, a server may place limits on how much may be cached at once, and there is no way
       to control if writes to a cached area have write-through or write-back semantics.  In
       fact, the cache command can always fail and still be compliant, and success might not
       guarantee a performance gain.

       If this callback is omitted, then the results of ".can_cache" determine whether nbdkit
       will reject cache requests, treat them as instant success, or emulate caching by calling
       ".pread" over the same region and ignoring the results.

       This function will not be called if ".can_cache" did not return "NBDKIT_CACHE_NATIVE".

       The "flags" parameter exists in case of future NBD protocol extensions; at this time, it
       will be 0 on input.  A plugin must fail this function if "flags" includes an unrecognized
       flag, as that may indicate a requirement that the plugin must comply with to provide a
       specific caching semantic.

       If there is an error, ".cache" should call "nbdkit_error" with an error message, and
       "nbdkit_set_error" to record an appropriate error (unless "errno" is sufficient), then
       return "-1".

   ".errno_is_preserved"
       This field defaults to 0; if non-zero, nbdkit can reliably use the value of "errno" when a
       callback reports failure, rather than the plugin having to call "nbdkit_set_error".

SHUTDOWN

       When nbdkit receives certain signals it will shut down (see "SIGNALS" in nbdkit(1)).  The
       server will wait for any currently running plugin callbacks to finish, call ".close" on
       those connections, then call the ".cleanup" and ".unload" callbacks before unloading the
       plugin.

       Note that it's not guaranteed this can always happen (eg. the server might be killed by
       "SIGKILL" or segfault).

   Requesting asynchronous shutdown
       Plugins and filters can call exit(3) in the configuration phase (before and including
       ".get_ready", but not in connected callbacks).

       Once nbdkit has started serving connections, plugins and filters should not call exit(3).
       However they may instruct nbdkit to shut down by calling "nbdkit_shutdown", or to
       disconnect a single client by calling "nbdkit_disconnect":

        void nbdkit_shutdown (void);

       This function requests an asynchronous shutdown and returns (note that it does not exit
       the process immediately).  It ensures that the plugin and all filters are unloaded cleanly
       which may take some time.  Further callbacks from nbdkit into the plugin or filter may
       occur after you have called this.

        void nbdkit_disconnect (int force);

       This function requests that the current connection be disconnected (note that it does not
       affect other connections, and the client may try to reconnect).  It is only useful from
       connected callbacks (that is, after ".open" and before ".close").  If "force" is true,
       nbdkit will disconnect the client immediately, and the client will not receive any
       response to the current command or any other commands in flight in parallel threads;
       otherwise, nbdkit will not accept any new commands from the client (failing all commands
       other than "NBD_CMD_DISC" with "ESHUTDOWN"), but will allow existing commands to complete
       gracefully.  Either way, the next callback for the current connection should be ".close".

PARSING COMMAND LINE PARAMETERS

   Parsing numbers
       There are several functions for parsing numbers.  These all deal correctly with overflow,
       out of range and parse errors, and you should use them instead of unsafe functions like
       sscanf(3), atoi(3) and similar.

        int nbdkit_parse_int (const char *what, const char *str, int *r);
        int nbdkit_parse_unsigned (const char *what,
                                   const char *str, unsigned *r);
        int nbdkit_parse_int8_t (const char *what,
                                 const char *str, int8_t *r);
        int nbdkit_parse_uint8_t (const char *what,
                                  const char *str, uint8_t *r);
        int nbdkit_parse_int16_t (const char *what,
                                  const char *str, int16_t *r);
        int nbdkit_parse_uint16_t (const char *what,
                                   const char *str, uint16_t *r);
        int nbdkit_parse_int32_t (const char *what,
                                  const char *str, int32_t *r);
        int nbdkit_parse_uint32_t (const char *what,
                                   const char *str, uint32_t *r);
        int nbdkit_parse_int64_t (const char *what,
                                  const char *str, int64_t *r);
        int nbdkit_parse_uint64_t (const char *what,
                                   const char *str, uint64_t *r);

       Parse string "str" into an integer of various types.  These functions parse a decimal,
       hexadecimal ("0x...") or octal ("0...") number.

       On success the functions return 0 and set *r to the parsed value (unless "*r == NULL" in
       which case the result is discarded).  On error, "nbdkit_error" is called and the functions
       return "-1".  On error *r is always unchanged.

       The "what" parameter is printed in error messages to provide context.  It should usually
       be a short descriptive string of what you are trying to parse, eg:

        if (nbdkit_parse_int ("random seed", value, &seed) == -1)
          return -1;

       might print an error:

        random seed: could not parse number: "lalala"

   Parsing sizes
       Use the "nbdkit_parse_size" utility function to parse human-readable size strings such as
       "100M" into the size in bytes.

        int64_t nbdkit_parse_size (const char *str);

       "str" can be a string in a number of common formats.  The function returns the size in
       bytes.  If there was an error, it returns "-1".

   Parsing booleans
       Use the "nbdkit_parse_bool" utility function to parse human-readable strings such as "on"
       into a boolean value.

        int nbdkit_parse_bool (const char *str);

       "str" can be a string containing a case-insensitive form of various common toggle values.
       The function returns 0 or 1 if the parse was successful.  If there was an error, it
       returns "-1".

   Reading passwords
       The "nbdkit_read_password" utility function can be used to read passwords from config
       parameters:

        int nbdkit_read_password (const char *value, char **password);

       For example:

        char *password = NULL;

        static int
        myplugin_config (const char *key, const char *value)
        {
          ..
          if (strcmp (key, "password") == 0) {
            free (password);
            if (nbdkit_read_password (value, &password) == -1)
              return -1;
          }
          ..
        }

       The "password" result string is allocated by malloc, and so you may need to free it.

       This function recognizes several password formats.  A password may be used directly on the
       command line, eg:

        nbdkit myplugin password=mostsecret

       But more securely this function can also read a password interactively:

        nbdkit myplugin password=-

       or from a file:

        nbdkit myplugin password=+/tmp/secret

       or from a file descriptor inherited by nbdkit:

        nbdkit myplugin password=-99

       Notes on reading passwords

       If the password begins with a "-" or "+" character then it must be passed in a file.

       "password=-" can only be used when stdin is a terminal.

       "password=-FD" cannot be used with stdin, stdout or stderr (ie. "-0", "-1" or "-2").  The
       reason is that after reading the password the file descriptor is closed, which causes bad
       stuff to happen.

   Safely interacting with stdin and stdout
        int nbdkit_stdio_safe (void);

       The "nbdkit_stdio_safe" utility function returns 1 if it is safe to interact with stdin
       and stdout during the configuration phase, and 0 otherwise.  This is because when the
       nbdkit -s option is used the plugin must not directly interact with stdin, because that
       would interfere with the client.

       The result of this function only matters in callbacks up to ".config_complete".  Once
       nbdkit reaches ".get_ready", the plugin should assume that nbdkit may have closed the
       original stdin and stdout in order to become a daemon.

       nbdkit-sh-plugin(3) uses this function to determine whether it is safe to support
       "script=-" to read a script from stdin.  Also constructs like "password=-" (see "Reading
       passwords" above) are disabled when reading from stdio is not safe.

FILENAMES AND PATHS

       The server usually (not always) changes directory to "/" before it starts serving
       connections.  This means that any relative paths passed during configuration will not work
       when the server is running (example: "nbdkit plugin.so disk.img").

       To avoid problems, prepend relative paths with the current directory before storing them
       in the handle.  Or open files and store the file descriptor.

   "nbdkit_absolute_path"
        char *nbdkit_absolute_path (const char *filename);

       The utility function "nbdkit_absolute_path" converts any path to an absolute path: if it
       is relative, then all this function does is prepend the current working directory to the
       path, with no extra checks.

       Note that this function works only when used in the ".config", ".config_complete" and
       ".get_ready" callbacks.

       If conversion was not possible, this calls "nbdkit_error" and returns "NULL".  Note that
       this function does not check that the file exists.

       The returned string must be freed by the caller.

   "nbdkit_realpath"
        char *nbdkit_realpath (const char *filename);

       The utility function "nbdkit_realpath" converts any path to an absolute path, resolving
       symlinks.  Under the hood it uses the "realpath" function, and thus it fails if the path
       does not exist, or it is not possible to access to any of the components of the path.

       Note that this function works only when used in the ".config", ".config_complete" and
       ".get_ready" callbacks.

       If the path resolution was not possible, this calls "nbdkit_error" and returns "NULL".

       The returned string must be freed by the caller.

   umask
       All plugins will see a umask(2) of 0022.

SLEEPING

       A plugin that needs to sleep may call sleep(2), nanosleep(2) and similar.  However that
       can cause nbdkit to delay excessively when shutting down (since it must wait for any
       plugin or filter which is sleeping).  To avoid this there is a special wrapper around
       nanosleep which plugins and filters should use instead.

   "nbdkit_nanosleep"
        int nbdkit_nanosleep (unsigned sec, unsigned nsec);

       The utility function "nbdkit_nanosleep" suspends the current thread, and returns 0 if it
       slept at least as many seconds and nanoseconds as requested, or -1 after calling
       "nbdkit_error" if there is no point in continuing the current command.  Attempts to sleep
       more than "INT_MAX" seconds are treated as an error.

EXPORT NAME

       If the client negotiated an NBD export name with nbdkit then plugins may read this from
       any connected callbacks.  Nbdkit's normal behaviour is to accept any export name passed by
       the client, log it in debug output, but otherwise ignore it.  By using
       "nbdkit_export_name" plugins may choose to filter by export name or serve different
       content.

   "nbdkit_export_name"
        const char *nbdkit_export_name (void);

       Return the optional NBD export name if one was negotiated with the current client (this
       uses thread-local magic so no parameter is required).  The returned string is valid at
       least through the ".close" of the current connection, but if you need to store it in the
       plugin for use by more than one client you must copy it.

       The export name is a free-form text string, it is not necessarily a path or filename and
       it does not need to begin with a '/' character.  The NBD protocol describes the empty
       string ("") as a representing a "default export" or to be used in cases where the export
       name does not make sense.  The export name is untrusted client data, be cautious when
       parsing it.

       On error, "nbdkit_error" is called and the call returns "NULL".

STRING LIFETIME

       Some callbacks are specified to return "const char *", even when a plugin may not have a
       suitable compile-time constant to return.  Returning dynamically-allocated memory for such
       a callback would induce a memory leak or otherwise complicate the plugin to perform
       additional bookkeeping.  For these cases, nbdkit provides several convenience functions
       for creating a copy of a string for better lifetime management.

   "nbdkit_strdup_intern"
   "nbdkit_strndup_intern"
        const char *nbdkit_strdup_intern (const char *str);
        const char *nbdkit_strndup_intern (const char *str, size_t n);

       Returns a copy of "str", possibly limited to a maximum of "n" bytes, so that the caller
       may reclaim str and use the copy in its place.  If the copy is created outside the scope
       of a connection (such as during ".load" or ".config"), the lifetime of the copy will last
       at least through ".unload".  If the copy is created after a client has triggered a
       connection (such as during ".preconnect" or ".open"), the lifetime will last at least
       through ".close", but the copy is not safe to share with other connections.

       On error, "nbdkit_error" is called and the call returns "NULL".

   "nbdkit_printf_intern"
   "nbdkit_vprintf_intern"
        const char *nbdkit_printf_intern (const char *fmt, ...);
        const char *nbdkit_vprintf_intern (const char *fmt, va_list ap);

       Return a string created from a format template, with a lifetime longer than the current
       connection.  Shorthand for passing "fmt" to asprintf(3) on a temporary string, then
       passing that result to "nbdkit_strdup_intern".

       On error, "nbdkit_error" is called and the call returns "NULL".

AUTHENTICATION

       A server may use "nbdkit_is_tls" to limit which export names work until after a client has
       completed TLS authentication.  See nbdkit-tls(1).  It is also possible to use
       nbdkit-tls-fallback-filter(1) to automatically ensure that the plugin is only used with
       authentication.

   "nbdkit_is_tls"
        int nbdkit_is_tls (void);

       Return true if the client has completed TLS authentication, or false if the connection is
       still plaintext.

       On error (such as calling this function outside of the context of ".open"), "nbdkit_error"
       is called and the call returns "-1".

PEER NAME

       It is possible to get the source address of the client when you are running in any
       connected callback.

   "nbdkit_peer_name"
        int nbdkit_peer_name (struct sockaddr *addr, socklen_t *addrlen);

       Return the peer (client) address, if available.  The "addr" and "addrlen" parameters
       behave like getpeername(2).  In particular you must initialize "addrlen" with the size of
       the buffer pointed to by "addr", and if "addr" is not large enough then the address will
       be truncated.

       In some cases this is not available or the address returned will be meaningless (eg. if
       there is a proxy between the client and nbdkit).  This call uses thread-local magic so no
       parameter is required to specify the current connection.

       On success this returns 0.  On error, "nbdkit_error" is called and this call returns "-1".

   "nbdkit_peer_pid"
       (nbdkit ≥ 1.24, Linux only)

        int64_t nbdkit_peer_pid (void);

       Return the peer process ID.  This is only available when the client connected over a Unix
       domain socket.

       On success this returns the peer process ID.  On error, "nbdkit_error" is called and this
       call returns "-1".

   "nbdkit_peer_uid"
       (nbdkit ≥ 1.24)

        int64_t nbdkit_peer_uid (void);

       Return the peer user ID.  This is only available when the client connected over a Unix
       domain socket.

       On success this returns the user ID.  On error, "nbdkit_error" is called and this call
       returns "-1".

   "nbdkit_peer_gid"
       (nbdkit ≥ 1.24)

        int64_t nbdkit_peer_gid (void);

       Return the peer group ID.  This is only available when the client connected over a Unix
       domain socket.

       On success this returns the user ID.  On error, "nbdkit_error" is called and this call
       returns "-1".

VERSION

   Compile-time version of nbdkit
       The macros "NBDKIT_VERSION_MAJOR", "NBDKIT_VERSION_MINOR" and "NBDKIT_VERSION_MICRO"
       expand to integers containing the version of the nbdkit headers that you are compiling
       against.

       "NBDKIT_VERSION_MAJOR" is always 1.  "NBDKIT_VERSION_MINOR" is even for stable releases of
       nbdkit and odd for development releases.

       The macro "NBDKIT_VERSION_STRING" expands to the same version as a string.

   Run-time version of nbdkit
       When the plugin is loaded into nbdkit, it may not be the same version that it was compiled
       against.  nbdkit guarantees backwards compatibility of the API and ABI, so provided that
       nbdkit is the same version or newer, the plugin will still work.  There is no way to get
       the version of nbdkit from the plugin.

   Version of the plugin
       The plugin itself can use any versioning scheme you want, and put any string into the
       ".version" field of the plugin struct (or leave the field NULL).

   API version
       See "WRITING AN NBDKIT PLUGIN" above.

DEBUGGING

       Run the server with -f and -v options so it doesn't fork and you can see debugging
       information:

        nbdkit -fv ./myplugin.so [key=value [key=value [...]]]

       To print debugging information from within the plugin, call "nbdkit_debug", which has the
       following prototype and works like printf(3):

        void nbdkit_debug (const char *fs, ...);
        void nbdkit_vdebug (const char *fs, va_list args);

       For convenience, "nbdkit_debug" preserves the value of "errno", and also supports the
       glibc extension of a single %m in a format string expanding to "strerror(errno)", even on
       platforms that don't support that natively. Note that "nbdkit_debug" only prints things
       when the server is in verbose mode (-v option).

   Debug Flags
       The -v option switches general debugging on or off, and this debugging should be used for
       messages which are useful for all users of your plugin.

       In cases where you want to enable specific extra debugging to track down bugs in plugins
       or filters — mainly for use by the plugin/filter developers themselves — you can define
       Debug Flags.  These are global ints called "myplugin_debug_*":

        int myplugin_debug_foo;
        int myplugin_debug_bar;
        ...
        if (myplugin_debug_foo) {
          nbdkit_debug ("lots of extra debugging about foo: ...");
        }

       Debug Flags can be controlled on the command line using the -D (or --debug) option:

        nbdkit -f -v -D myplugin.foo=1 -D myplugin.bar=2 myplugin [...]

       Note "myplugin" is the name passed to ".name" in the "struct nbdkit_plugin".

       You should only use this feature for debug settings.  For general settings use ordinary
       plugin parameters.  Debug Flags can only be C ints.  They are not supported by non-C
       language plugins.

       For convenience '.' characters are replaced with '_' characters in the variable name, so
       both of these parameters:

        -D myplugin.foo_bar=1
        -D myplugin.foo.bar=1

       correspond to the plugin variable "myplugin_debug_foo_bar".

COMPILING THE PLUGIN

       Plugins should be compiled as shared libraries.  There are various ways to achieve this,
       but most Linux compilers support a -shared option to create the shared library directly,
       for example:

        gcc -fPIC -shared myplugin.c -o myplugin.so

       Note that the shared library will have undefined symbols for functions that you call like
       "nbdkit_parse_int" or "nbdkit_error".  These will be resolved by the server binary when
       nbdkit dlopens the plugin.

   PKG-CONFIG/PKGCONF
       nbdkit provides a pkg-config/pkgconf file called "nbdkit.pc" which should be installed on
       the correct path when the nbdkit plugin development environment is installed.  You can use
       this in autoconf configure.ac scripts to test for the development environment:

        PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])

       The above will fail unless nbdkit ≥ 1.2.3 and the header file is installed, and will set
       "NBDKIT_CFLAGS" and "NBDKIT_LIBS" appropriately for compiling plugins.

       You can also run pkg-config/pkgconf directly, for example:

        if ! pkg-config nbdkit --exists; then
          echo "you must install the nbdkit plugin development environment"
          exit 1
        fi

       You can also substitute the plugindir variable by doing:

        PKG_CHECK_VAR([NBDKIT_PLUGINDIR], [nbdkit], [plugindir])

       which defines "$(NBDKIT_PLUGINDIR)" in automake-generated Makefiles.

       If nbdkit development headers are installed in a non-standard location then you may need
       to compile plugins using:

        gcc -fPIC -shared myplugin.c -o myplugin.so \
          `pkg-config nbdkit --cflags --libs`

INSTALLING THE PLUGIN

       The plugin is a "*.so" file and possibly a manual page.  You can of course install the
       plugin "*.so" file wherever you want, and users will be able to use it by running:

        nbdkit /path/to/plugin.so [args]

       However if the shared library has a name of the form "nbdkit-name-plugin.so" and if the
       library is installed in the $plugindir directory, then users can be run it by only typing:

        nbdkit name [args]

       The location of the $plugindir directory is set when nbdkit is compiled and can be found
       by doing:

        nbdkit --dump-config

       If using the pkg-config/pkgconf system then you can also find the plugin directory at
       compile time by doing:

        pkg-config nbdkit --variable=plugindir

WRITING PLUGINS IN C++

       Plugins in C++ work almost exactly like those in C, but the way you define the
       "nbdkit_plugin" struct is slightly different:

        namespace {
          nbdkit_plugin create_plugin() {
            nbdkit_plugin plugin = nbdkit_plugin ();
            plugin.name     = "myplugin";
            plugin.open     = myplugin_open;
            plugin.get_size = myplugin_get_size;
            plugin.pread    = myplugin_pread;
            plugin.pwrite   = myplugin_pwrite;
            return plugin;
          }
        }
        static struct nbdkit_plugin plugin = create_plugin ();
        NBDKIT_REGISTER_PLUGIN(plugin)

WRITING PLUGINS IN OTHER PROGRAMMING LANGUAGES

       You can also write nbdkit plugins in Go, Lua, OCaml, Perl, Python, Ruby, Rust, shell
       script or Tcl.  Other programming languages may be offered in future.

       For more information see: nbdkit-cc-plugin(3), nbdkit-golang-plugin(3),
       nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3),
       nbdkit-python-plugin(3), nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3),
       nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .

       Plugins written in scripting languages may also be installed in $plugindir.  These must be
       called "nbdkit-name-plugin" without any extension.  They must be executable, and they must
       use the shebang header (see "Shebang scripts" in nbdkit(1)).  For example a plugin written
       in Perl called "foo.pl" might be installed like this:

        $ head -1 foo.pl
        #!/usr/sbin/nbdkit perl

        $ sudo install -m 0755 foo.pl $plugindir/nbdkit-foo-plugin

       and then users will be able to run it like this:

        $ nbdkit foo [args ...]

SEE ALSO

       nbdkit(1), nbdkit-nozero-filter(1), nbdkit-tls-fallback-filter(1), nbdkit-filter(3).

       Standard plugins provided by nbdkit:

       nbdkit-blkio-plugin(1), nbdkit-cdi-plugin(1), nbdkit-curl-plugin(1),
       nbdkit-data-plugin(1), nbdkit-eval-plugin(1), nbdkit-example1-plugin(1),
       nbdkit-example2-plugin(1), nbdkit-example3-plugin(1), nbdkit-example4-plugin(1),
       nbdkit-file-plugin(1), nbdkit-floppy-plugin(1), nbdkit-full-plugin(1),
       nbdkit-guestfs-plugin(1), nbdkit-info-plugin(1), nbdkit-iso-plugin(1),
       nbdkit-libvirt-plugin(1), nbdkit-linuxdisk-plugin(1), nbdkit-memory-plugin(1),
       nbdkit-nbd-plugin(1), nbdkit-null-plugin(1), nbdkit-ondemand-plugin(1),
       nbdkit-partitioning-plugin(1), nbdkit-pattern-plugin(1), nbdkit-random-plugin(1),
       nbdkit-S3-plugin(1), nbdkit-sparse-random-plugin(1), nbdkit-split-plugin(1),
       nbdkit-ssh-plugin(1), nbdkit-tmpdisk-plugin(1), nbdkit-torrent-plugin(1),
       nbdkit-vddk-plugin(1), nbdkit-zero-plugin(1) ; nbdkit-cc-plugin(3),
       nbdkit-golang-plugin(3), nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3),
       nbdkit-perl-plugin(3), nbdkit-python-plugin(3), nbdkit-ruby-plugin(3),
       nbdkit-rust-plugin(3), nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .

AUTHORS

       Eric Blake

       Richard W.M. Jones

       Pino Toscano

COPYRIGHT

       Copyright Red Hat

LICENSE

       Redistribution and use in source and binary forms, with or without modification, are
       permitted provided that the following conditions are met:

       •   Redistributions of source code must retain the above copyright notice, this list of
           conditions and the following disclaimer.

       •   Redistributions in binary form must reproduce the above copyright notice, this list of
           conditions and the following disclaimer in the documentation and/or other materials
           provided with the distribution.

       •   Neither the name of Red Hat nor the names of its contributors may be used to endorse
           or promote products derived from this software without specific prior written
           permission.

       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS OR IMPLIED
       WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
       FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS
       BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
       DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
       OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
       LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
       POSSIBILITY OF SUCH DAMAGE.