Provided by: nbdkit-plugin-dev_1.16.2-1ubuntu3_amd64 bug

NAME

       nbdkit-filter - how to write nbdkit filters

SYNOPSIS

        #include <nbdkit-filter.h>

        static int
        myfilter_config (nbdkit_next_config *next, void *nxdata,
                         const char *key, const char *value)
        {
          if (strcmp (key, "myparameter") == 0) {
            // ...
            return 0;
          }
          else {
            // pass through to next filter or plugin
            return next (nxdata, key, value);
          }
        }

        static struct nbdkit_filter filter = {
          .name              = "filter",
          .config            = myfilter_config,
          /* etc */
        };

        NBDKIT_REGISTER_FILTER(filter)

       When this has been compiled to a shared library, do:

        nbdkit [--args ...] --filter=./myfilter.so plugin [key=value ...]

       When debugging, use the -fv options:

        nbdkit -fv --filter=./myfilter.so plugin [key=value ...]

DESCRIPTION

       One or more nbdkit filters can be placed in front of an nbdkit plugin to modify the
       behaviour of the plugin.  This manual page describes how to create an nbdkit filter.

       Filters can be used for example to limit requests to an offset/limit, add copy-on-write
       support, or inject delays or errors (for testing).

       Different filters can be stacked:

            NBD     ┌─────────┐    ┌─────────┐          ┌────────┐
         client ───▶│ filter1 │───▶│ filter2 │── ─ ─ ──▶│ plugin │
        request     └─────────┘    └─────────┘          └────────┘

       Each filter intercepts plugin functions (see nbdkit-plugin(3)) and can call the next
       filter or plugin in the chain, modifying parameters, calling before the filter function,
       in the middle or after.  Filters may even short-cut the chain.  As an example, to process
       its own parameters the filter can intercept the ".config" method:

        static int
        myfilter_config (nbdkit_next_config *next, void *nxdata,
                         const char *key, const char *value)
        {
          if (strcmp (key, "myparameter") == 0) {
            // ...
            // here you would handle this key, value
            // ...
            return 0;
          }
          else {
            // pass through to next filter or plugin
            return next (nxdata, key, value);
          }
        }

        static struct nbdkit_filter filter = {
          // ...
          .config            = myfilter_config,
          // ...
        };

       The call to "next (nxdata, ...)" calls the ".config" method of the next filter or plugin
       in the chain.  In the example above any instances of "myparameter=..." on the command line
       would not be seen by the plugin.

       To see example filters: https://github.com/libguestfs/nbdkit/tree/master/filters

       Filters must be written in C.

       Unlike plugins, where we provide a stable ABI guarantee that permits operation across
       version differences, filters can only be run with the same version of nbdkit that they
       were compiled with.  The reason for this is two-fold: the filter API includes access to
       struct nbdkit_next_ops that is likely to change if new callbacks are added (old nbdkit
       cannot safely run new filters that access new methods); and if we added new methods then
       an old filter would not see them and so they would be passed unmodified through the
       filter, and in some cases that leads to data corruption (new nbdkit cannot safely run old
       filters unaware of new methods).  Therefore, unlike plugins, you should not expect to
       distribute filters separately from nbdkit.

"#include <nbdkit-filter.h>"

       All filters should start by including this header file.

"struct nbdkit_filter"

       All filters must define and register one "struct nbdkit_filter", which contains the name
       of the filter and pointers to plugin methods that the filter wants to intercept.

        static struct nbdkit_filter filter = {
          .name              = "filter",
          .longname          = "My Filter",
          .description       = "This is my great filter for nbdkit",
          .config            = myfilter_config,
          /* etc */
        };

        NBDKIT_REGISTER_FILTER(filter)

       The ".name" field is the name of the filter.  This is the only field which is required.

NEXT PLUGIN

       nbdkit-filter.h defines three function types ("nbdkit_next_config",
       "nbdkit_next_config_complete", "nbdkit_next_open") and a structure called "struct
       nbdkit_next_ops".  These abstract the next plugin or filter in the chain.  There is also
       an opaque pointer "nxdata" which must be passed along when calling these functions.

   Next config, open and close
       The filter’s ".config", ".config_complete" and ".open" methods may only call the next
       ".config", ".config_complete" and ".open" method in the chain (optionally for ".config").

       The filter’s ".close" method is called when an old connection closed, and this has no
       "next" parameter because it cannot be short-circuited.

   "next_ops"
       The filter’s other methods like ".prepare", ".get_size", ".pread" etc ― always called in
       the context of a connection ― are passed a pointer to "struct nbdkit_next_ops" which
       contains a comparable set of accessors to plugin methods that can be called during a
       connection.

       It is possible for a filter to issue (for example) extra "next_ops->pread" calls in
       response to a single ".pwrite" call.

       Note that the semantics of the functions in "struct nbdkit_next_ops" are slightly
       different from what a plugin implements: for example, when a plugin's ".pread" returns -1
       on error, the error value to advertise to the client is implicit (via the plugin calling
       "nbdkit_set_error" or setting "errno"), whereas "next_ops->pread" exposes this via an
       explicit parameter, allowing a filter to learn or modify this error if desired.

       There is also a "next_ops->reopen" function which is used by nbdkit-retry-filter(3) to
       close and reopen the underlying plugin.  It should be used with caution because it is
       difficult to use safely.

   Other considerations
       You can modify parameters when you call the "next" function.  However be careful when
       modifying strings because for some methods (eg. ".config") the plugin may save the string
       pointer that you pass along.  So you may have to ensure that the string is not freed for
       the lifetime of the server.

       Note that if your filter registers a callback but in that callback it doesn't call the
       "next" function then the corresponding method in the plugin will never be called.  In
       particular, your ".open" method, if you have one, must call the ".next" method.

CALLBACKS

       "struct nbdkit_filter" has some static fields describing the filter and optional callback
       functions which can be used to intercept plugin methods.

   ".name"
        const char *name;

       This field (a string) is required, and must contain only ASCII alphanumeric characters and
       be unique amongst all filters.

   ".longname"
        const char *longname;

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

   ".description"
        const char *description;

       An optional multi-line description of the filter.

   ".load"
        void load (void);

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

   ".unload"
        void unload (void);

       This may be called once just before the filter 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 filter as robust as possible by not requiring
       cleanup.  See also "SHUTDOWN" in nbdkit-plugin(3).

   ".config"
        int (*config) (nbdkit_next_config *next, void *nxdata,
                       const char *key, const char *value);

       This intercepts the plugin ".config" method and can be used by the filter to parse its own
       command line parameters.  You should try to make sure that command line parameter keys
       that the filter uses do not conflict with ones that could be used by a plugin.

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

   ".config_complete"
        int (*config_complete) (nbdkit_next_config_complete *next, void *nxdata);

       This intercepts the plugin ".config_complete" method and can be used to ensure that all
       parameters needed by the filter were supplied on the command line.

       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 filter doesn't take any config parameters you should probably omit this.

   ".thread_model"
        int (*thread_model) (void);

       Filters may tighten (but not relax) the thread model of the plugin, by defining this
       callback.  Note that while plugins use a compile-time definition of "THREAD_MODEL",
       filters do not need to declare a model at compile time; instead, this callback is called
       after ".config_complete" and before any connections are created.  See "THREADS" in
       nbdkit-plugin(3) for a discussion of thread models.

       The final thread model used by nbdkit is the smallest (ie. most serialized) out of all the
       filters and the plugin, and applies for all connections.  Requests for a model larger than
       permitted by the plugin are silently ignored. It is acceptable for decisions made during
       ".config" and ".config_complete" to determine which model to request.

       This callback is optional; if it is not present, the filter must be written to handle
       fully parallel requests, including when multiple requests are issued in parallel on the
       same connection, similar to a plugin requesting "NBDKIT_THREAD_MODEL_PARALLEL".  This
       ensures the filter doesn't slow down other filters or plugins.

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

   ".open"
        void * (*open) (nbdkit_next_open *next, void *nxdata,
                        int readonly);

       This is called when a new client connection is opened and can be used to allocate any per-
       connection data structures needed by the filter.  The handle (which is not the same as the
       plugin handle) is passed back to other filter 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.

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

       This callback is optional, but if provided, it must call "next", passing a value for
       "readonly" according to how the filter plans to use the plugin.  Typically, the filter
       passes the same value as it received, or passes true to provide a writable layer on top of
       a read-only backend.  However, it is also acceptable to attempt write access to the plugin
       even if this filter is readonly, such as when a file system mounted read-only still
       requires write access to the underlying device in case a journal needs to be replayed for
       consistency as part of the mounting process.  The filter should generally call "next" as
       its first step, to allocate from the plugin outwards, so that ".close" running from the
       outer filter to the plugin will be in reverse.

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

       This is called when the client closes the connection.  It should clean up any per-
       connection resources used by the filter.  It is called beginning with the outermost filter
       and ending with the plugin (the opposite order of ".open" if all filters call "next"
       first), although this order technically does not matter since the callback cannot report
       failures or access the underlying plugin.

   ".prepare"
   ".finalize"
         int (*prepare) (struct nbdkit_next_ops *next_ops, void *nxdata,
                         void *handle, int readonly);
         int (*finalize) (struct nbdkit_next_ops *next_ops, void *nxdata,
                          void *handle);

       These two methods can be used to perform any necessary operations just after opening the
       connection (".prepare") or just before closing the connection (".finalize").

       For example if you need to scan the underlying disk to check for a partition table, you
       could do it in your ".prepare" method (calling the plugin's ".pread" method via
       "next_ops").  Or if you need to cleanly update superblock data in the image on close you
       can do it in your ".finalize" method (calling the plugin's ".pwrite" method).  Doing these
       things in the filter's ".open" or ".close" method is not possible.

       For ".prepare", the value of "readonly" is the same as was passed to ".open", declaring
       how this filter will be used.

       There is no "next_ops->prepare" or "next_ops->finalize".  Unlike other filter methods,
       prepare and finalize are not chained through the "next_ops" structure.  Instead the core
       nbdkit server calls the prepare and finalize methods of all filters.  Prepare methods are
       called starting with the filter closest to the plugin and proceeding outwards (matching
       the order of ".open" if all filters call "next" before doing anything locally).  Finalize
       methods are called in the reverse order of prepare methods, with the outermost filter
       first (and matching the order of ".close"), and only if the prepare method succeeded.

       If there is an error, both callbacks should call "nbdkit_error" with an error message and
       return "-1".  An error in ".prepare" is reported to the client, but leaves the connection
       open (a client may try again with a different export name, for example); while an error in
       ".finalize" forces the client to disconnect.

   ".get_size"
        int64_t (*get_size) (struct nbdkit_next_ops *next_ops, void *nxdata,
                             void *handle);

       This intercepts the plugin ".get_size" method and can be used to read or modify the
       apparent size of the block device that the NBD client will see.

       The returned size must be ≥ 0.  If there is an error, ".get_size" should call
       "nbdkit_error" with an error message and return "-1".  This function is only called once
       per connection and cached by nbdkit.  Similarly, repeated calls to "next_ops->get_size"
       will return a cached value.

   ".can_write"
   ".can_flush"
   ".is_rotational"
   ".can_trim"
   ".can_zero"
   ".can_fast_zero"
   ".can_extents"
   ".can_fua"
   ".can_multi_conn"
   ".can_cache"
        int (*can_write) (struct nbdkit_next_ops *next_ops, void *nxdata,
                          void *handle);
        int (*can_flush) (struct nbdkit_next_ops *next_ops, void *nxdata,
                          void *handle);
        int (*is_rotational) (struct nbdkit_next_ops *next_ops,
                              void *nxdata,
                              void *handle);
        int (*can_trim) (struct nbdkit_next_ops *next_ops, void *nxdata,
                         void *handle);
        int (*can_zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
                         void *handle);
        int (*can_fast_zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
                              void *handle);
        int (*can_extents) (struct nbdkit_next_ops *next_ops, void *nxdata,
                            void *handle);
        int (*can_fua) (struct nbdkit_next_ops *next_ops, void *nxdata,
                        void *handle);
        int (*can_multi_conn) (struct nbdkit_next_ops *next_ops, void *nxdata,
                               void *handle);
        int (*can_cache) (struct nbdkit_next_ops *next_ops, void *nxdata,
                          void *handle);

       These intercept the corresponding plugin methods, and control feature bits advertised to
       the client.

       Of note, the semantics of ".can_zero" callback in the filter are slightly different from
       the plugin, and must be one of three success values visible only to filters:

       "NBDKIT_ZERO_NONE"
           Completely suppress advertisement of write zero support (this can only be done from
           filters, not plugins).

       "NBDKIT_ZERO_EMULATE"
           Inform nbdkit that write zeroes should immediately fall back to ".pwrite" emulation
           without trying ".zero" (this value is returned by "next_ops->can_zero" if the plugin
           returned false in its ".can_zero").

       "NBDKIT_ZERO_NATIVE"
           Inform nbdkit that write zeroes should attempt to use ".zero", although it may still
           fall back to ".pwrite" emulation for "ENOTSUP" or "EOPNOTSUPP" failures (this value is
           returned by "next_ops->can_zero" if the plugin returned true in its ".can_zero").

       Remember that most of the feature check functions return merely a boolean success value,
       while ".can_zero", ".can_fua" and ".can_cache" have three success values.

       The difference between ".can_fua" values may affect choices made in the filter: when
       splitting a write request that requested FUA from the client, if "next_ops->can_fua"
       returns "NBDKIT_FUA_NATIVE", then the filter should pass the FUA flag on to each sub-
       request; while if it is known that FUA is emulated by a flush because of a return of
       "NBDKIT_FUA_EMULATE", it is more efficient to only flush once after all sub-requests have
       completed (often by passing "NBDKIT_FLAG_FUA" on to only the final sub-request, or by
       dropping the flag and ending with a direct call to "next_ops->flush").

       If there is an error, the callback should call "nbdkit_error" with an error message and
       return "-1".  These functions are called at most once per connection and cached by nbdkit.
       Similarly, repeated calls to any of the "next_ops" counterparts will return a cached
       value; by calling into the plugin during ".prepare", you can ensure that later use of the
       cached values during data commands like <.pwrite> will not fail.

   ".pread"
        int (*pread) (struct nbdkit_next_ops *next_ops, void *nxdata,
                      void *handle, void *buf, uint32_t count, uint64_t offset,
                      uint32_t flags, int *err);

       This intercepts the plugin ".pread" method and can be used to read or modify data read by
       the plugin.

       The parameter "flags" exists in case of future NBD protocol extensions; at this time, it
       will be 0 on input, and the filter should not pass any flags to "next_ops->pread".

       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 return -1 with "err" set to the
       positive errno value to return to the client.

   ".pwrite"
        int (*pwrite) (struct nbdkit_next_ops *next_ops, void *nxdata,
                       void *handle,
                       const void *buf, uint32_t count, uint64_t offset,
                       uint32_t flags, int *err);

       This intercepts the plugin ".pwrite" method and can be used to modify data written by the
       plugin.

       This function will not be called if ".can_write" returned false; in turn, the filter
       should not call "next_ops->pwrite" if "next_ops->can_write" did not return true.

       The parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on the result of
       ".can_fua".  In turn, the filter should only pass "NBDKIT_FLAG_FUA" on to
       "next_ops->pwrite" if "next_ops->can_fua" returned a positive value.

       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 return -1 with "err" set to the
       positive errno value to return to the client.

   ".flush"
        int (*flush) (struct nbdkit_next_ops *next_ops, void *nxdata,
                      void *handle, uint32_t flags, int *err);

       This intercepts the plugin ".flush" method and can be used to modify flush requests.

       This function will not be called if ".can_flush" returned false; in turn, the filter
       should not call "next_ops->flush" if "next_ops->can_flush" did not return true.

       The parameter "flags" exists in case of future NBD protocol extensions; at this time, it
       will be 0 on input, and the filter should not pass any flags to "next_ops->flush".

       If there is an error, ".flush" should call "nbdkit_error" with an error message and return
       -1 with "err" set to the positive errno value to return to the client.

   ".trim"
        int (*trim) (struct nbdkit_next_ops *next_ops, void *nxdata,
                     void *handle, uint32_t count, uint64_t offset,
                     uint32_t flags, int *err);

       This intercepts the plugin ".trim" method and can be used to modify trim requests.

       This function will not be called if ".can_trim" returned false; in turn, the filter should
       not call "next_ops->trim" if "next_ops->can_trim" did not return true.

       The parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on the result of
       ".can_fua".  In turn, the filter should only pass "NBDKIT_FLAG_FUA" on to "next_ops->trim"
       if "next_ops->can_fua" returned a positive value.

       If there is an error, ".trim" should call "nbdkit_error" with an error message and return
       -1 with "err" set to the positive errno value to return to the client.

   ".zero"
        int (*zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
                     void *handle, uint32_t count, uint64_t offset, uint32_t flags,
                     int *err);

       This intercepts the plugin ".zero" method and can be used to modify zero requests.

       This function will not be called if ".can_zero" returned "NBDKIT_ZERO_NONE"; in turn, the
       filter should not call "next_ops->zero" if "next_ops->can_zero" returned
       "NBDKIT_ZERO_NONE".

       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".  In turn, the filter may pass "NBDKIT_FLAG_MAY_TRIM"
       unconditionally, but should only pass "NBDKIT_FLAG_FUA" or "NBDKIT_FLAG_FAST_ZERO" on to
       "next_ops->zero" if the corresponding "next_ops->can_fua" or "next_ops->can_fast_zero"
       returned a positive value.

       Note that unlike the plugin ".zero" which is permitted to fail with "ENOTSUP" or
       "EOPNOTSUPP" to force a fallback to ".pwrite", the function "next_ops->zero" will not fail
       with "err" set to "ENOTSUP" or "EOPNOTSUPP" unless "NBDKIT_FLAG_FAST_ZERO" was used,
       because otherwise the fallback has already taken place.

       If there is an error, ".zero" should call "nbdkit_error" with an error message and return
       -1 with "err" set to the positive errno value to return to the client.  The filter should
       not fail with "ENOTSUP" or "EOPNOTSUPP" unless "flags" includes "NBDKIT_FLAG_FAST_ZERO"
       (while plugins have automatic fallback to ".pwrite", filters do not).

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

       This intercepts the plugin ".extents" method and can be used to modify extent requests.

       This function will not be called if ".can_extents" returned false; in turn, the filter
       should not call "next_ops->extents" if "next_ops->can_extents" did not return true.

       It is possible for filters to transform the extents list received back from the layer
       below.  Without error checking it would look like this:

        myfilter_extents (..., uint32_t count, uint64_t offset, ...)
        {
          size_t i;
          struct nbdkit_extents *extents2;
          struct nbdkit_extent e;
          int64_t size;

          size = next_ops->get_size (nxdata);
          extents2 = nbdkit_extents_new (offset + shift, size);
          next_ops->extents (nxdata, count, offset + shift, flags, extents2, err);
          for (i = 0; i < nbdkit_extents_count (extents2); ++i) {
            e = nbdkit_get_extent (extents2, i);
            e.offset -= shift;
            nbdkit_add_extent (extents, e.offset, e.length, e.type);
          }
          nbdkit_extents_free (extents2);
        }

       If there is an error, ".extents" should call "nbdkit_error" with an error message and
       return -1 with "err" set to the positive errno value to return to the client.

       Allocating and freeing nbdkit_extents list

       Two functions are provided to filters only for allocating and freeing the map:

        struct nbdkit_extents *nbdkit_extents_new (uint64_t start, uint64_t end);

       Allocates and returns a new, empty extents list.  The "start" parameter is the start of
       the range described in the list, and the "end" parameter is the offset of the byte beyond
       the end.  Normally you would pass in "offset" as the start and the size of the plugin as
       the end, but for filters which adjust offsets, they should pass in the adjusted offset.

       On error this function can return "NULL".  In this case it calls "nbdkit_error" and/or
       "nbdkit_set_error" as required.  "errno" will be set to a suitable value.

        void nbdkit_extents_free (struct nbdkit_extents *);

       Frees an existing extents list.

       Iterating over nbdkit_extents list

       Two functions are provided to filters only to iterate over the extents in order:

        size_t nbdkit_extents_count (const struct nbdkit_extents *);

       Returns the number of extents in the list.

        struct nbdkit_extent {
          uint64_t offset;
          uint64_t length;
          uint32_t type;
        };
        struct nbdkit_extent nbdkit_get_extent (const struct nbdkit_extents *,
                                                size_t i);

       Returns a copy of the "i"'th extent.

   ".cache"
        int (*cache) (struct nbdkit_next_ops *next_ops, void *nxdata,
                      void *handle, uint32_t count, uint64_t offset,
                      uint32_t flags, int *err);

       This intercepts the plugin ".cache" method and can be used to modify cache requests.

       This function will not be called if ".can_cache" returned "NBDKIT_CACHE_NONE" or
       "NBDKIT_CACHE_EMULATE"; in turn, the filter should not call "next_ops->cache" unless
       "next_ops->can_cache" returned "NBDKIT_CACHE_NATIVE".

       The parameter "flags" exists in case of future NBD protocol extensions; at this time, it
       will be 0 on input, and the filter should not pass any flags to "next_ops->cache".

       If there is an error, ".cache" should call "nbdkit_error" with an error message and return
       -1 with "err" set to the positive errno value to return to the client.

ERROR HANDLING

       If there is an error in the filter itself, the filter should call "nbdkit_error" to report
       an error message.  If the callback is involved in serving data, the explicit "err"
       parameter determines the error code that will be sent to the client; other callbacks
       should return the appropriate error indication, eg. "NULL" or "-1".

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

DEBUGGING

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

        nbdkit -fv --filter=./myfilter.so plugin [key=value [key=value [...]]]

       To print debugging information from within the filter, 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
       Debug Flags in filters work exactly the same way as plugins.  See "Debug Flags" in
       nbdkit-plugin(3).

INSTALLING THE FILTER

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

        nbdkit --filter=/path/to/filter.so plugin [args]

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

        nbdkit --filter=name plugin [args]

       The location of the $filterdir 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 filter directory at
       compile time by doing:

        pkgconf nbdkit --variable=filterdir

PKG-CONFIG/PKGCONF

       nbdkit provides a pkg-config/pkgconf file called "nbdkit.pc" which should be installed on
       the correct path when the nbdkit 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 filters.

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

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

       You can also substitute the filterdir variable by doing:

        PKG_CHECK_VAR([NBDKIT_FILTERDIR], [nbdkit], [filterdir])

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

SEE ALSO

       nbdkit(1), nbdkit-plugin(3).

       Standard filters provided by nbdkit:

       nbdkit-blocksize-filter(1), nbdkit-cache-filter(1), nbdkit-cacheextents-filter(1),
       nbdkit-cow-filter(1), nbdkit-delay-filter(1), nbdkit-error-filter(1),
       nbdkit-fua-filter(1), nbdkit-log-filter(1), nbdkit-nocache-filter(1),
       nbdkit-noextents-filter(1), nbdkit-noparallel-filter(1), nbdkit-nozero-filter(1),
       nbdkit-offset-filter(1), nbdkit-partition-filter(1), nbdkit-rate-filter(1),
       nbdkit-readahead-filter(1), nbdkit-retry-filter(1), nbdkit-stats-filter(1),
       nbdkit-truncate-filter(1), nbdkit-xz-filter(1) .

AUTHORS

       Eric Blake

       Richard W.M. Jones

COPYRIGHT

       Copyright (C) 2013-2019 Red Hat Inc.

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.