API and ABI guarantee for C plugins

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.

"#define NBDKIT_API_VERSION 2"

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>"

"#define THREAD_MODEL ..."

 #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS

"struct nbdkit_plugin"

 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

         ┌──────────────────┐
         │ 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
                   │           and starts serving clients
                   │
        ┌──────────┴─────────────┬─ ─ ─ ─ ─ ─ ─ ─ ─
 ┌──────┴─────┐ client #1        │
 │ preconnect │                  │
 └──────┬─────┘                  │
 ┌──────┴─────┐                  │
 │ open       │                  │
 └──────┬─────┘                  │
 ┌──────┴─────┐  NBD option      │
 │ can_write  │  negotiation     │
 └──────┬─────┘                  │
 ┌──────┴─────┐           ┌──────┴─────┐ client #2
 │ get_size   │           │ preconnect │
 └──────┬─────┘           └──────┬─────┘
 ┌──────┴─────┐ data      ┌──────┴─────┐
 │ pread      │ serving   │ open       │
 └──────┬─────┘↺          └──────┬─────┘
 ┌──────┴─────┐                 ...
 │ pwrite     │
 └──────┬─────┘↺          ┌──────┴─────┐
 ┌──────┴─────┐           │ close      │
 │ close      │           └────────────┘
 └────────────┘
 
                   │           before nbdkit exits
                   │
         ┌─────────┴────────┐
         │ unload           │
         └──────────────────┘

".load"

is called once just after the plugin is loaded into memory.

".config" and ".config_complete"

".config" is called zero or more times during command line parsing. ".config_complete" is called once after all configuration information has been passed to the plugin (but not during "nbdkit --dump-plugin").

Both are called after loading the plugin but before any connections are accepted.

".thread_model"

In normal operation, ".thread_model" is called once after ".config_complete" has validated all configuration information, and before any connections are accepted. However, during "nbdkit --dump-plugin", it is called after any ".config" calls but without ".config_complete" (so a plugin which determines the results from a script must be prepared for a missing script).

".get_ready"

In normal operation, ".get_ready" is called before the server starts serving. It is called before the server forks or changes directory. It is the last chance to do any global preparation that is needed to serve connections.

".preconnect"

Called when a TCP connection has been made to the server. This happens early, before NBD or TLS negotiation.

".open"

A new client has connected and finished the NBD handshake. TLS negotiation (if required) 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.

".close"

The client has disconnected.

".preconnect", ".open" ... ".close"

The sequence ".preconnect", ".open" ... ".close" can be called repeatedly over the lifetime of the plugin, and can be called in parallel (depending on the thread model).

".unload"

is called once just before the plugin is unloaded from memory.

Flags

"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

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 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);

".name"

 const char *name;

This field (a string) is required, and must contain only ASCII alphanumeric characters 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.

".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 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".

".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" against a whitelist (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".

".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.

This callback is called after the NBD handshake has completed, which includes TLS authentication (if required). If the plugin defines a ".preconnect" callback, then it must be called and return with success before ".open" is called.

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".

".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 operation. The nature of the caching is unspecified (including whether there are limits on how much can be cached at once, and whether writes to a cached region have write-through or write-back semantics), but the command exists to let clients issue a hint to the server that they will be accessing that region of the export.

If this returns "NBDKIT_CACHE_NONE", cache support is not advertised to the client; if this returns "NBDKIT_CACHE_EMULATE", caching is emulated by the server calling ".pread" and ignoring the results; if this returns "NBDKIT_CACHE_NATIVE", then the ".cache" callback will be used. 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 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 parameter "flags" 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 comply must with 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"

Requesting asynchronous shutdown

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":

 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.

Parsing numbers

 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", argv[1], &seed) == -1)
   return -1;

might print an error:

 random seed: could not parse number: "lalala"

Parsing sizes

 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

 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

 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.

"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

"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.

"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 only valid while the client is connected, so if you need to store it in the plugin 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".

"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".

Debug Flags

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".

PKG-CONFIG/PKGCONF

 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`