.\" Automatically generated by Podwrapper::Man 1.24.1 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdkit-filter 3"
.TH nbdkit-filter 3 "2021-01-20" "nbdkit-1.24.1" "NBDKIT"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
nbdkit\-filter \- how to write nbdkit filters
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #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)
.Ve
.PP
When this has been compiled to a shared library, do:
.PP
.Vb 1
\& nbdkit [\-\-args ...] \-\-filter=./myfilter.so plugin [key=value ...]
.Ve
.PP
When debugging, use the \fI\-fv\fR options:
.PP
.Vb 1
\& nbdkit \-fv \-\-filter=./myfilter.so plugin [key=value ...]
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
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).
.PP
Different filters can be stacked:
.PP
.Vb 3
\&     NBD     ┌─────────┐    ┌─────────┐          ┌────────┐
\&  client ───▶│ filter1 │───▶│ filter2 │── ─ ─ ──▶│ plugin │
\& request     └─────────┘    └─────────┘          └────────┘
.Ve
.PP
Each filter intercepts plugin functions (see \fBnbdkit\-plugin\fR\|(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 \f(CW\*(C`.config\*(C'\fR method:
.PP
.Vb 10
\& 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,
\&   // ...
\& };
.Ve
.PP
The call to \f(CW\*(C`next (nxdata, ...)\*(C'\fR calls the \f(CW\*(C`.config\*(C'\fR method of the
next filter or plugin in the chain.  In the example above any
instances of \f(CW\*(C`myparameter=...\*(C'\fR on the command line would not be seen
by the plugin.
.PP
To see example filters:
https://github.com/libguestfs/nbdkit/tree/master/filters
.PP
Filters must be written in C.
.PP
Unlike plugins, where we provide a stable \s-1ABI\s0 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 \s-1API\s0 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.
.ie n .SH """#include <nbdkit\-filter.h>"""
.el .SH "\f(CW#include <nbdkit\-filter.h>\fP"
.IX Header "#include <nbdkit-filter.h>"
All filters should start by including this header file.
.ie n .SH """struct nbdkit_filter"""
.el .SH "\f(CWstruct nbdkit_filter\fP"
.IX Header "struct nbdkit_filter"
All filters must define and register one \f(CW\*(C`struct nbdkit_filter\*(C'\fR,
which contains the name of the filter and pointers to plugin methods
that the filter wants to intercept.
.PP
.Vb 7
\& 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)
.Ve
.PP
The \f(CW\*(C`.name\*(C'\fR field is the name of the filter.  This is the only field
which is required.
.SH "NEXT PLUGIN"
.IX Header "NEXT PLUGIN"
\&\fInbdkit\-filter.h\fR defines some function types (\f(CW\*(C`nbdkit_next_config\*(C'\fR,
\&\f(CW\*(C`nbdkit_next_config_complete\*(C'\fR, \f(CW\*(C`nbdkit_next_get_ready\*(C'\fR,
\&\f(CW\*(C`nbdkit_next_after_fork\*(C'\fR, \f(CW\*(C`nbdkit_next_preconnect\*(C'\fR,
\&\f(CW\*(C`nbdkit_next_list_exports\*(C'\fR, \f(CW\*(C`nbdkit_next_default_export\*(C'\fR,
\&\f(CW\*(C`nbdkit_next_open\*(C'\fR) and a structure called \f(CW\*(C`struct nbdkit_next_ops\*(C'\fR.
These abstract the next plugin or filter in the chain.  There is also
an opaque pointer \f(CW\*(C`nxdata\*(C'\fR which must be passed along when calling
these functions.  The value of \f(CW\*(C`nxdata\*(C'\fR passed to \f(CW\*(C`.open\*(C'\fR has a
stable lifetime that lasts to the corresponding \f(CW\*(C`.close\*(C'\fR, with all
intermediate functions (such as \f(CW\*(C`.pread\*(C'\fR) receiving the same value
for convenience.  Functions where \f(CW\*(C`nxdata\*(C'\fR is not reused are
\&\f(CW\*(C`.config\*(C'\fR, \f(CW\*(C`.config_complete\*(C'\fR, \f(CW\*(C`.get_ready\*(C'\fR, and \f(CW\*(C`.after_fork\*(C'\fR,
which are called during initialization outside any connections, and
\&\f(CW\*(C`.preconnect\*(C'\fR, \f(CW\*(C`.list_exports\*(C'\fR, and \f(CW\*(C`.default_export\*(C'\fR, which are
called based on client connections but prior to the stable lifetime of
\&\f(CW\*(C`.open\*(C'\fR.
.SS "Next config, open and close"
.IX Subsection "Next config, open and close"
The filter’s \f(CW\*(C`.config\*(C'\fR, \f(CW\*(C`.config_complete\*(C'\fR, \f(CW\*(C`.get_ready\*(C'\fR,
\&\f(CW\*(C`.after_fork\*(C'\fR and \f(CW\*(C`.open\*(C'\fR methods may only call the next \f(CW\*(C`.config\*(C'\fR,
\&\f(CW\*(C`.config_complete\*(C'\fR, \f(CW\*(C`.get_ready\*(C'\fR, \f(CW\*(C`.after_fork\*(C'\fR and \f(CW\*(C`.open\*(C'\fR method
in the chain (optionally for \f(CW\*(C`.config\*(C'\fR).
.PP
The filter’s \f(CW\*(C`.close\*(C'\fR method is called when an old connection closed,
and this has no \f(CW\*(C`next\*(C'\fR parameter because it cannot be
short-circuited.
.ie n .SS """next_ops"""
.el .SS "\f(CWnext_ops\fP"
.IX Subsection "next_ops"
The filter’s other methods like \f(CW\*(C`.prepare\*(C'\fR, \f(CW\*(C`.get_size\*(C'\fR, \f(CW\*(C`.pread\*(C'\fR
etc ― always called in the context of a connection ― are passed a
pointer to \f(CW\*(C`struct nbdkit_next_ops\*(C'\fR which contains a comparable set
of accessors to plugin methods that can be called during a connection.
The \f(CW\*(C`next_ops\*(C'\fR parameter is stable between \f(CW\*(C`.prepare\*(C'\fR and
\&\f(CW\*(C`.finalize\*(C'\fR; intermediate functions (such as \f(CW\*(C`.pread\*(C'\fR) receive the
same value for convenience.
.PP
It is possible for a filter to issue (for example) extra
\&\f(CW\*(C`next_ops\->pread\*(C'\fR calls in response to a single \f(CW\*(C`.pwrite\*(C'\fR call.
.PP
Note that the semantics of the functions in \f(CW\*(C`struct nbdkit_next_ops\*(C'\fR
are slightly different from what a plugin implements: for example,
when a plugin's \f(CW\*(C`.pread\*(C'\fR returns \-1 on error, the error value to
advertise to the client is implicit (via the plugin calling
\&\f(CW\*(C`nbdkit_set_error\*(C'\fR or setting \f(CW\*(C`errno\*(C'\fR), whereas
\&\f(CW\*(C`next_ops\->pread\*(C'\fR exposes this via an explicit parameter,
allowing a filter to learn or modify this error if desired.
.PP
There is also a \f(CW\*(C`next_ops\->reopen\*(C'\fR function which is used by
\&\fBnbdkit\-retry\-filter\fR\|(1) to close and reopen the underlying plugin.
It should be used with caution because it is difficult to use safely.
.SS "Other considerations"
.IX Subsection "Other considerations"
You can modify parameters when you call the \f(CW\*(C`next\*(C'\fR function.  However
be careful when modifying strings because for some methods
(eg. \f(CW\*(C`.config\*(C'\fR) 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; you may find \f(CW\*(C`nbdkit_strdup_intern\*(C'\fR helpful
for avoiding a memory leak while still obeying lifecycle constraints.
.PP
Note that if your filter registers a callback but in that callback it
doesn't call the \f(CW\*(C`next\*(C'\fR function then the corresponding method in the
plugin will never be called.  In particular, your \f(CW\*(C`.open\*(C'\fR method, if
you have one, \fBmust\fR call the \f(CW\*(C`.next\*(C'\fR method.
.SH "CALLBACKS"
.IX Header "CALLBACKS"
\&\f(CW\*(C`struct nbdkit_filter\*(C'\fR has some static fields describing the filter
and optional callback functions which can be used to intercept plugin
methods.
.ie n .SS """.name"""
.el .SS "\f(CW.name\fP"
.IX Subsection ".name"
.Vb 1
\& const char *name;
.Ve
.PP
This field (a string) is required, and \fBmust\fR contain only \s-1ASCII\s0
alphanumeric characters or non-leading dashes, and be unique amongst
all filters.
.ie n .SS """.longname"""
.el .SS "\f(CW.longname\fP"
.IX Subsection ".longname"
.Vb 1
\& const char *longname;
.Ve
.PP
An optional free text name of the filter.  This field is used in error
messages.
.ie n .SS """.description"""
.el .SS "\f(CW.description\fP"
.IX Subsection ".description"
.Vb 1
\& const char *description;
.Ve
.PP
An optional multi-line description of the filter.
.ie n .SS """.load"""
.el .SS "\f(CW.load\fP"
.IX Subsection ".load"
.Vb 1
\& void load (void);
.Ve
.PP
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.
.ie n .SS """.unload"""
.el .SS "\f(CW.unload\fP"
.IX Subsection ".unload"
.Vb 1
\& void unload (void);
.Ve
.PP
This may be called once just before the filter is unloaded from
memory.  Note that it's not guaranteed that \f(CW\*(C`.unload\*(C'\fR 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 \*(L"\s-1SHUTDOWN\*(R"\s0 in \fBnbdkit\-plugin\fR\|(3).
.ie n .SS """.config"""
.el .SS "\f(CW.config\fP"
.IX Subsection ".config"
.Vb 2
\& int (*config) (nbdkit_next_config *next, void *nxdata,
\&                const char *key, const char *value);
.Ve
.PP
This intercepts the plugin \f(CW\*(C`.config\*(C'\fR 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.
.PP
If there is an error, \f(CW\*(C`.config\*(C'\fR should call \f(CW\*(C`nbdkit_error\*(C'\fR with an
error message and return \f(CW\*(C`\-1\*(C'\fR.
.ie n .SS """.config_complete"""
.el .SS "\f(CW.config_complete\fP"
.IX Subsection ".config_complete"
.Vb 1
\& int (*config_complete) (nbdkit_next_config_complete *next, void *nxdata);
.Ve
.PP
This intercepts the plugin \f(CW\*(C`.config_complete\*(C'\fR method and can be used
to ensure that all parameters needed by the filter were supplied on
the command line.
.PP
If there is an error, \f(CW\*(C`.config_complete\*(C'\fR should call \f(CW\*(C`nbdkit_error\*(C'\fR
with an error message and return \f(CW\*(C`\-1\*(C'\fR.
.ie n .SS """.config_help"""
.el .SS "\f(CW.config_help\fP"
.IX Subsection ".config_help"
.Vb 1
\& const char *config_help;
.Ve
.PP
This optional multi-line help message should summarize any
\&\f(CW\*(C`key=value\*(C'\fR parameters that it takes.  It does \fInot\fR need to repeat
what already appears in \f(CW\*(C`.description\*(C'\fR.
.PP
If the filter doesn't take any config parameters you should probably
omit this.
.ie n .SS """.thread_model"""
.el .SS "\f(CW.thread_model\fP"
.IX Subsection ".thread_model"
.Vb 1
\& int (*thread_model) (void);
.Ve
.PP
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 \f(CW\*(C`THREAD_MODEL\*(C'\fR, filters do not need to declare a model
at compile time; instead, this callback is called after
\&\f(CW\*(C`.config_complete\*(C'\fR and before any connections are created.  See
\&\*(L"\s-1THREADS\*(R"\s0 in \fBnbdkit\-plugin\fR\|(3) for a discussion of thread models.
.PP
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
\&\f(CW\*(C`.config\*(C'\fR and \f(CW\*(C`.config_complete\*(C'\fR to determine which model to
request.
.PP
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 \f(CW\*(C`NBDKIT_THREAD_MODEL_PARALLEL\*(C'\fR.  This ensures the
filter doesn't slow down other filters or plugins.
.PP
If there is an error, \f(CW\*(C`.thread_model\*(C'\fR should call \f(CW\*(C`nbdkit_error\*(C'\fR
with an error message and return \f(CW\*(C`\-1\*(C'\fR.
.ie n .SS """.get_ready"""
.el .SS "\f(CW.get_ready\fP"
.IX Subsection ".get_ready"
.Vb 2
\& int (*get_ready) (nbdkit_next_get_ready *next, void *nxdata,
\&                   int thread_model);
.Ve
.PP
This intercepts the plugin \f(CW\*(C`.get_ready\*(C'\fR method and can be used by the
filter to get ready to serve requests.
.PP
The \f(CW\*(C`thread_model\*(C'\fR parameter informs the filter about the final
thread model chosen by nbdkit after considering the results of
\&\f(CW\*(C`.thread_model\*(C'\fR of all filters in the chain after
\&\f(CW\*(C`.config_complete\*(C'\fR.  This does not need to be passed on to \f(CW\*(C`next\*(C'\fR,
as the model can no longer be altered at this point.
.PP
If there is an error, \f(CW\*(C`.get_ready\*(C'\fR should call \f(CW\*(C`nbdkit_error\*(C'\fR with
an error message and return \f(CW\*(C`\-1\*(C'\fR.
.ie n .SS """.after_fork"""
.el .SS "\f(CW.after_fork\fP"
.IX Subsection ".after_fork"
.Vb 1
\& int (*after_fork) (nbdkit_next_after_fork *next, void *nxdata);
.Ve
.PP
This intercepts the plugin \f(CW\*(C`.after_fork\*(C'\fR method and can be used by
the filter to start background threads (although these have limited
usefulness since they will not be able to access the plugin).
.PP
If there is an error, \f(CW\*(C`.after_fork\*(C'\fR should call \f(CW\*(C`nbdkit_error\*(C'\fR with
an error message and return \f(CW\*(C`\-1\*(C'\fR.
.ie n .SS """.preconnect"""
.el .SS "\f(CW.preconnect\fP"
.IX Subsection ".preconnect"
.Vb 2
\& int (*preconnect) (nbdkit_next_preconnect *next, void *nxdata,
\&                    int readonly);
.Ve
.PP
This intercepts the plugin \f(CW\*(C`.preconnect\*(C'\fR method and can be used to
filter access to the server.
.PP
If there is an error, \f(CW\*(C`.preconnect\*(C'\fR should call \f(CW\*(C`nbdkit_error\*(C'\fR with
an error message and return \f(CW\*(C`\-1\*(C'\fR.
.ie n .SS """.list_exports"""
.el .SS "\f(CW.list_exports\fP"
.IX Subsection ".list_exports"
.Vb 3
\& int (*list_exports) (nbdkit_next_list_exports *next, void *nxdata,
\&                      int readonly, int is_tls,
\&                      struct nbdkit_exports *exports);
.Ve
.PP
This intercepts the plugin \f(CW\*(C`.list_exports\*(C'\fR method and can be used to
filter which exports are advertised.
.PP
The \f(CW\*(C`readonly\*(C'\fR parameter matches what is passed to <.preconnect> and
\&\f(CW\*(C`.open\*(C'\fR, and may be changed by the filter when calling into the
plugin.  The \f(CW\*(C`is_tls\*(C'\fR parameter informs the filter whether \s-1TLS\s0
negotiation has been completed by the client, but is not passed on to
\&\f(CW\*(C`next\*(C'\fR because it cannot be altered.
.PP
It is possible for filters to transform the exports list received back
from the layer below.  Without error checking it would look like this:
.PP
.Vb 6
\& myfilter_list_exports (...)
\& {
\&   size_t i;
\&   struct nbdkit_exports *exports2;
\&   struct nbdkit_export e;
\&   char *name, *desc;
\&
\&   exports2 = nbdkit_exports_new ();
\&   next_list_exports (nxdata, readonly, exports);
\&   for (i = 0; i < nbdkit_exports_count (exports2); ++i) {
\&     e = nbdkit_get_export (exports2, i);
\&     name = adjust (e.name);
\&     desc = adjust (e.desc);
\&     nbdkit_add_export (exports, name, desc);
\&     free (name);
\&     free (desc);
\&   }
\&   nbdkit_exports_free (exports2);
\& }
.Ve
.PP
If there is an error, \f(CW\*(C`.list_exports\*(C'\fR should call \f(CW\*(C`nbdkit_error\*(C'\fR with
an error message and return \f(CW\*(C`\-1\*(C'\fR.
.PP
\fIAllocating and freeing nbdkit_exports list\fR
.IX Subsection "Allocating and freeing nbdkit_exports list"
.PP
Two functions are provided to filters only for allocating and freeing
the list:
.PP
.Vb 1
\& struct nbdkit_exports *nbdkit_exports_new (void);
.Ve
.PP
Allocates and returns a new, empty exports list.
.PP
On error this function can return \f(CW\*(C`NULL\*(C'\fR.  In this case it calls
\&\f(CW\*(C`nbdkit_error\*(C'\fR as required.  \f(CW\*(C`errno\*(C'\fR will be set to a suitable
value.
.PP
.Vb 1
\& void nbdkit_exports_free (struct nbdkit_exports *);
.Ve
.PP
Frees an existing exports list.
.PP
\fIIterating over nbdkit_exports list\fR
.IX Subsection "Iterating over nbdkit_exports list"
.PP
Two functions are provided to filters only to iterate over the exports
in order:
.PP
.Vb 1
\& size_t nbdkit_exports_count (const struct nbdkit_exports *);
.Ve
.PP
Returns the number of exports in the list.
.PP
.Vb 6
\& struct nbdkit_export {
\&   char *name;
\&   char *description;
\& };
\& const struct nbdkit_export nbdkit_get_export (const struct nbdkit_exports *,
\&                                               size_t i);
.Ve
.PP
Returns a copy of the \f(CW\*(C`i\*(C'\fR'th export.
.ie n .SS """.default_export"""
.el .SS "\f(CW.default_export\fP"
.IX Subsection ".default_export"
.Vb 2
\& const char *default_export (nbdkit_next_default_export *next, void *nxdata,
\&                             int readonly, int is_tls)
.Ve
.PP
This intercepts the plugin \f(CW\*(C`.default_export\*(C'\fR method and can be used to
alter the canonical export name used in place of the default \f(CW""\fR.
.PP
The \f(CW\*(C`readonly\*(C'\fR parameter matches what is passed to <.preconnect> and
\&\f(CW\*(C`.open\*(C'\fR, and may be changed by the filter when calling into the
plugin.  The \f(CW\*(C`is_tls\*(C'\fR parameter informs the filter whether \s-1TLS\s0
negotiation has been completed by the client, but is not passed on to
\&\f(CW\*(C`next\*(C'\fR because it cannot be altered.
.ie n .SS """.open"""
.el .SS "\f(CW.open\fP"
.IX Subsection ".open"
.Vb 2
\& void * (*open) (nbdkit_next_open *next, void *nxdata,
\&                 int readonly, const char *exportname, int is_tls);
.Ve
.PP
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 \f(CW\*(C`.close\*(C'\fR
callback.
.PP
Note that the handle is completely opaque to nbdkit, but it must not
be \s-1NULL.\s0  If you don't need to use a handle, return
\&\f(CW\*(C`NBDKIT_HANDLE_NOT_NEEDED\*(C'\fR which is a static non-NULL pointer.
.PP
If there is an error, \f(CW\*(C`.open\*(C'\fR should call \f(CW\*(C`nbdkit_error\*(C'\fR with an
error message and return \f(CW\*(C`NULL\*(C'\fR.
.PP
This callback is optional, but if provided, it should call \f(CW\*(C`next\*(C'\fR,
passing \f(CW\*(C`readonly\*(C'\fR and \f(CW\*(C`exportname\*(C'\fR possibly modified according to
how the filter plans to use the plugin (\f(CW\*(C`is_tls\*(C'\fR is not passed,
because a filter cannot modify it).  Typically, the filter passes the
same values as it received, or passes readonly=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.
.PP
The \f(CW\*(C`exportname\*(C'\fR string is only guaranteed to be available during the
call (different than the lifetime for the return of \f(CW\*(C`nbdkit_export_name\*(C'\fR
used by plugins).  If the filter needs to use it (other than immediately
passing it down to the next layer) it must take a copy, although
\&\f(CW\*(C`nbdkit_strdup_intern\*(C'\fR is useful for this task.  The \f(CW\*(C`exportname\*(C'\fR and
\&\f(CW\*(C`is_tls\*(C'\fR parameters are provided so that filters do not need to use
the plugin-only interfaces of \f(CW\*(C`nbdkit_export_name\*(C'\fR and
\&\f(CW\*(C`nbdkit_is_tls\*(C'\fR.
.PP
The filter should generally call \f(CW\*(C`next\*(C'\fR as its first step, to
allocate from the plugin outwards, so that \f(CW\*(C`.close\*(C'\fR running from the
outer filter to the plugin will be in reverse.  Skipping a call to
\&\f(CW\*(C`next\*(C'\fR is acceptable if the filter will not access \f(CW\*(C`next_ops\*(C'\fR
during any of the remaining callbacks reached on the same connection.
.ie n .SS """.close"""
.el .SS "\f(CW.close\fP"
.IX Subsection ".close"
.Vb 1
\& void (*close) (void *handle);
.Ve
.PP
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 \f(CW\*(C`.open\*(C'\fR if all filters call \f(CW\*(C`next\*(C'\fR first),
although this order technically does not matter since the callback
cannot report failures or access the underlying plugin.
.ie n .SS """.prepare"""
.el .SS "\f(CW.prepare\fP"
.IX Subsection ".prepare"
.ie n .SS """.finalize"""
.el .SS "\f(CW.finalize\fP"
.IX Subsection ".finalize"
.Vb 4
\&  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);
.Ve
.PP
These two methods can be used to perform any necessary operations just
after opening the connection (\f(CW\*(C`.prepare\*(C'\fR) or just before closing the
connection (\f(CW\*(C`.finalize\*(C'\fR).
.PP
For example if you need to scan the underlying disk to check for a
partition table, you could do it in your \f(CW\*(C`.prepare\*(C'\fR method (calling
the plugin's \f(CW\*(C`.get_size\*(C'\fR and \f(CW\*(C`.pread\*(C'\fR methods via \f(CW\*(C`next_ops\*(C'\fR).  Or
if you need to cleanly update superblock data in the image on close
you can do it in your \f(CW\*(C`.finalize\*(C'\fR method (calling the plugin's
\&\f(CW\*(C`.pwrite\*(C'\fR method).  Doing these things in the filter's \f(CW\*(C`.open\*(C'\fR or
\&\f(CW\*(C`.close\*(C'\fR method is not possible.
.PP
For \f(CW\*(C`.prepare\*(C'\fR, the value of \f(CW\*(C`readonly\*(C'\fR is the same as was passed to
\&\f(CW\*(C`.open\*(C'\fR, declaring how this filter will be used.
.PP
Note that nbdkit performs sanity checking on requests made to the
underlying plugin; for example, \f(CW\*(C`next_ops\->pread\*(C'\fR cannot be
called on a given connection unless \f(CW\*(C`next_ops\->get_size\*(C'\fR has
first been called at least once in the same connection (to ensure the
read requests are in bounds), and \f(CW\*(C`next_ops\->pwrite\*(C'\fR further
requires an earlier successful call to \f(CW\*(C`next_ops\->can_write\*(C'\fR.  In
many filters, these prerequisites will be automatically called during
the client negotiation phase, but there are cases where a filter
overrides query functions or makes I/O calls into the plugin before
handshaking is complete, where the filter needs to make those
prerequisite calls manually during \f(CW\*(C`.prepare\*(C'\fR.
.PP
There is no \f(CW\*(C`next_ops\->prepare\*(C'\fR or \f(CW\*(C`next_ops\->finalize\*(C'\fR.
Unlike other filter methods, prepare and finalize are not chained
through the \f(CW\*(C`next_ops\*(C'\fR 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 \f(CW\*(C`.open\*(C'\fR if all filters
call \f(CW\*(C`next\*(C'\fR before doing anything locally), and only when an outer
filter did not skip the \f(CW\*(C`next\*(C'\fR call during \f(CW\*(C`.open\*(C'\fR.  Finalize
methods are called in the reverse order of prepare methods, with the
outermost filter first (and matching the order of \f(CW\*(C`.close\*(C'\fR), and only
if the prepare method succeeded.
.PP
If there is an error, both callbacks should call \f(CW\*(C`nbdkit_error\*(C'\fR with
an error message and return \f(CW\*(C`\-1\*(C'\fR.  An error in \f(CW\*(C`.prepare\*(C'\fR 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 \f(CW\*(C`.finalize\*(C'\fR forces the client to disconnect.
.ie n .SS """.get_size"""
.el .SS "\f(CW.get_size\fP"
.IX Subsection ".get_size"
.Vb 2
\& int64_t (*get_size) (struct nbdkit_next_ops *next_ops, void *nxdata,
\&                      void *handle);
.Ve
.PP
This intercepts the plugin \f(CW\*(C`.get_size\*(C'\fR method and can be used to read
or modify the apparent size of the block device that the \s-1NBD\s0 client
will see.
.PP
The returned size must be ≥ 0.  If there is an error, \f(CW\*(C`.get_size\*(C'\fR
should call \f(CW\*(C`nbdkit_error\*(C'\fR with an error message and return \f(CW\*(C`\-1\*(C'\fR.
This function is only called once per connection and cached by nbdkit.
Similarly, repeated calls to \f(CW\*(C`next_ops\->get_size\*(C'\fR will return a
cached value.
.ie n .SS """.export_description"""
.el .SS "\f(CW.export_description\fP"
.IX Subsection ".export_description"
.Vb 2
\& const char *export_description (struct nbdkit_next_ops *next_ops,
\&                                 void *nxdata, void *handle);
.Ve
.PP
This intercepts the plugin \f(CW\*(C`.export_description\*(C'\fR method and can be
used to read or modify the export description that the \s-1NBD\s0 client
will see.
.ie n .SS """.can_write"""
.el .SS "\f(CW.can_write\fP"
.IX Subsection ".can_write"
.ie n .SS """.can_flush"""
.el .SS "\f(CW.can_flush\fP"
.IX Subsection ".can_flush"
.ie n .SS """.is_rotational"""
.el .SS "\f(CW.is_rotational\fP"
.IX Subsection ".is_rotational"
.ie n .SS """.can_trim"""
.el .SS "\f(CW.can_trim\fP"
.IX Subsection ".can_trim"
.ie n .SS """.can_zero"""
.el .SS "\f(CW.can_zero\fP"
.IX Subsection ".can_zero"
.ie n .SS """.can_fast_zero"""
.el .SS "\f(CW.can_fast_zero\fP"
.IX Subsection ".can_fast_zero"
.ie n .SS """.can_extents"""
.el .SS "\f(CW.can_extents\fP"
.IX Subsection ".can_extents"
.ie n .SS """.can_fua"""
.el .SS "\f(CW.can_fua\fP"
.IX Subsection ".can_fua"
.ie n .SS """.can_multi_conn"""
.el .SS "\f(CW.can_multi_conn\fP"
.IX Subsection ".can_multi_conn"
.ie n .SS """.can_cache"""
.el .SS "\f(CW.can_cache\fP"
.IX Subsection ".can_cache"
.Vb 10
\& 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);
.Ve
.PP
These intercept the corresponding plugin methods, and control feature
bits advertised to the client.
.PP
Of note, the semantics of \f(CW\*(C`.can_zero\*(C'\fR callback in the filter are
slightly different from the plugin, and must be one of three success
values visible only to filters:
.ie n .IP """NBDKIT_ZERO_NONE""" 4
.el .IP "\f(CWNBDKIT_ZERO_NONE\fR" 4
.IX Item "NBDKIT_ZERO_NONE"
Completely suppress advertisement of write zero support (this can only
be done from filters, not plugins).
.ie n .IP """NBDKIT_ZERO_EMULATE""" 4
.el .IP "\f(CWNBDKIT_ZERO_EMULATE\fR" 4
.IX Item "NBDKIT_ZERO_EMULATE"
Inform nbdkit that write zeroes should immediately fall back to
\&\f(CW\*(C`.pwrite\*(C'\fR emulation without trying \f(CW\*(C`.zero\*(C'\fR (this value is returned
by \f(CW\*(C`next_ops\->can_zero\*(C'\fR if the plugin returned false in its
\&\f(CW\*(C`.can_zero\*(C'\fR).
.ie n .IP """NBDKIT_ZERO_NATIVE""" 4
.el .IP "\f(CWNBDKIT_ZERO_NATIVE\fR" 4
.IX Item "NBDKIT_ZERO_NATIVE"
Inform nbdkit that write zeroes should attempt to use \f(CW\*(C`.zero\*(C'\fR,
although it may still fall back to \f(CW\*(C`.pwrite\*(C'\fR emulation for \f(CW\*(C`ENOTSUP\*(C'\fR
or \f(CW\*(C`EOPNOTSUPP\*(C'\fR failures (this value is returned by
\&\f(CW\*(C`next_ops\->can_zero\*(C'\fR if the plugin returned true in its
\&\f(CW\*(C`.can_zero\*(C'\fR).
.PP
Remember that most of the feature check functions return merely a
boolean success value, while \f(CW\*(C`.can_zero\*(C'\fR, \f(CW\*(C`.can_fua\*(C'\fR and
\&\f(CW\*(C`.can_cache\*(C'\fR have three success values.
.PP
The difference between \f(CW\*(C`.can_fua\*(C'\fR values may affect choices made in
the filter: when splitting a write request that requested \s-1FUA\s0 from the
client, if \f(CW\*(C`next_ops\->can_fua\*(C'\fR returns \f(CW\*(C`NBDKIT_FUA_NATIVE\*(C'\fR, then
the filter should pass the \s-1FUA\s0 flag on to each sub-request; while if
it is known that \s-1FUA\s0 is emulated by a flush because of a return of
\&\f(CW\*(C`NBDKIT_FUA_EMULATE\*(C'\fR, it is more efficient to only flush once after
all sub-requests have completed (often by passing \f(CW\*(C`NBDKIT_FLAG_FUA\*(C'\fR
on to only the final sub-request, or by dropping the flag and ending
with a direct call to \f(CW\*(C`next_ops\->flush\*(C'\fR).
.PP
If there is an error, the callback should call \f(CW\*(C`nbdkit_error\*(C'\fR with an
error message and return \f(CW\*(C`\-1\*(C'\fR.  These functions are called at most
once per connection and cached by nbdkit. Similarly, repeated calls to
any of the \f(CW\*(C`next_ops\*(C'\fR counterparts will return a cached value; by
calling into the plugin during \f(CW\*(C`.prepare\*(C'\fR, you can ensure that later
use of the cached values during data commands like <.pwrite> will not
fail.
.ie n .SS """.pread"""
.el .SS "\f(CW.pread\fP"
.IX Subsection ".pread"
.Vb 3
\& 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);
.Ve
.PP
This intercepts the plugin \f(CW\*(C`.pread\*(C'\fR method and can be used to read or
modify data read by the plugin.
.PP
The parameter \f(CW\*(C`flags\*(C'\fR exists in case of future \s-1NBD\s0 protocol
extensions; at this time, it will be 0 on input, and the filter should
not pass any flags to \f(CW\*(C`next_ops\->pread\*(C'\fR.
.PP
If there is an error (including a short read which couldn't be
recovered from), \f(CW\*(C`.pread\*(C'\fR should call \f(CW\*(C`nbdkit_error\*(C'\fR with an error
message \fBand\fR return \-1 with \f(CW\*(C`err\*(C'\fR set to the positive errno value
to return to the client.
.ie n .SS """.pwrite"""
.el .SS "\f(CW.pwrite\fP"
.IX Subsection ".pwrite"
.Vb 4
\& 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);
.Ve
.PP
This intercepts the plugin \f(CW\*(C`.pwrite\*(C'\fR method and can be used to modify
data written by the plugin.
.PP
This function will not be called if \f(CW\*(C`.can_write\*(C'\fR returned false; in
turn, the filter should not call \f(CW\*(C`next_ops\->pwrite\*(C'\fR if
\&\f(CW\*(C`next_ops\->can_write\*(C'\fR did not return true.
.PP
The parameter \f(CW\*(C`flags\*(C'\fR may include \f(CW\*(C`NBDKIT_FLAG_FUA\*(C'\fR on input based
on the result of \f(CW\*(C`.can_fua\*(C'\fR.  In turn, the filter should only pass
\&\f(CW\*(C`NBDKIT_FLAG_FUA\*(C'\fR on to \f(CW\*(C`next_ops\->pwrite\*(C'\fR if
\&\f(CW\*(C`next_ops\->can_fua\*(C'\fR returned a positive value.
.PP
If there is an error (including a short write which couldn't be
recovered from), \f(CW\*(C`.pwrite\*(C'\fR should call \f(CW\*(C`nbdkit_error\*(C'\fR with an error
message \fBand\fR return \-1 with \f(CW\*(C`err\*(C'\fR set to the positive errno value
to return to the client.
.ie n .SS """.flush"""
.el .SS "\f(CW.flush\fP"
.IX Subsection ".flush"
.Vb 2
\& int (*flush) (struct nbdkit_next_ops *next_ops, void *nxdata,
\&               void *handle, uint32_t flags, int *err);
.Ve
.PP
This intercepts the plugin \f(CW\*(C`.flush\*(C'\fR method and can be used to modify
flush requests.
.PP
This function will not be called if \f(CW\*(C`.can_flush\*(C'\fR returned false; in
turn, the filter should not call \f(CW\*(C`next_ops\->flush\*(C'\fR if
\&\f(CW\*(C`next_ops\->can_flush\*(C'\fR did not return true.
.PP
The parameter \f(CW\*(C`flags\*(C'\fR exists in case of future \s-1NBD\s0 protocol
extensions; at this time, it will be 0 on input, and the filter should
not pass any flags to \f(CW\*(C`next_ops\->flush\*(C'\fR.
.PP
If there is an error, \f(CW\*(C`.flush\*(C'\fR should call \f(CW\*(C`nbdkit_error\*(C'\fR with an
error message \fBand\fR return \-1 with \f(CW\*(C`err\*(C'\fR set to the positive errno
value to return to the client.
.ie n .SS """.trim"""
.el .SS "\f(CW.trim\fP"
.IX Subsection ".trim"
.Vb 3
\& int (*trim) (struct nbdkit_next_ops *next_ops, void *nxdata,
\&              void *handle, uint32_t count, uint64_t offset,
\&              uint32_t flags, int *err);
.Ve
.PP
This intercepts the plugin \f(CW\*(C`.trim\*(C'\fR method and can be used to modify
trim requests.
.PP
This function will not be called if \f(CW\*(C`.can_trim\*(C'\fR returned false; in
turn, the filter should not call \f(CW\*(C`next_ops\->trim\*(C'\fR if
\&\f(CW\*(C`next_ops\->can_trim\*(C'\fR did not return true.
.PP
The parameter \f(CW\*(C`flags\*(C'\fR may include \f(CW\*(C`NBDKIT_FLAG_FUA\*(C'\fR on input based
on the result of \f(CW\*(C`.can_fua\*(C'\fR.  In turn, the filter should only pass
\&\f(CW\*(C`NBDKIT_FLAG_FUA\*(C'\fR on to \f(CW\*(C`next_ops\->trim\*(C'\fR if
\&\f(CW\*(C`next_ops\->can_fua\*(C'\fR returned a positive value.
.PP
If there is an error, \f(CW\*(C`.trim\*(C'\fR should call \f(CW\*(C`nbdkit_error\*(C'\fR with an
error message \fBand\fR return \-1 with \f(CW\*(C`err\*(C'\fR set to the positive errno
value to return to the client.
.ie n .SS """.zero"""
.el .SS "\f(CW.zero\fP"
.IX Subsection ".zero"
.Vb 3
\& int (*zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
\&              void *handle, uint32_t count, uint64_t offset, uint32_t flags,
\&              int *err);
.Ve
.PP
This intercepts the plugin \f(CW\*(C`.zero\*(C'\fR method and can be used to modify
zero requests.
.PP
This function will not be called if \f(CW\*(C`.can_zero\*(C'\fR returned
\&\f(CW\*(C`NBDKIT_ZERO_NONE\*(C'\fR; in turn, the filter should not call
\&\f(CW\*(C`next_ops\->zero\*(C'\fR if \f(CW\*(C`next_ops\->can_zero\*(C'\fR returned
\&\f(CW\*(C`NBDKIT_ZERO_NONE\*(C'\fR.
.PP
On input, the parameter \f(CW\*(C`flags\*(C'\fR may include \f(CW\*(C`NBDKIT_FLAG_MAY_TRIM\*(C'\fR
unconditionally, \f(CW\*(C`NBDKIT_FLAG_FUA\*(C'\fR based on the result of
\&\f(CW\*(C`.can_fua\*(C'\fR, and \f(CW\*(C`NBDKIT_FLAG_FAST_ZERO\*(C'\fR based on the result of
\&\f(CW\*(C`.can_fast_zero\*(C'\fR.  In turn, the filter may pass
\&\f(CW\*(C`NBDKIT_FLAG_MAY_TRIM\*(C'\fR unconditionally, but should only pass
\&\f(CW\*(C`NBDKIT_FLAG_FUA\*(C'\fR or \f(CW\*(C`NBDKIT_FLAG_FAST_ZERO\*(C'\fR on to
\&\f(CW\*(C`next_ops\->zero\*(C'\fR if the corresponding \f(CW\*(C`next_ops\->can_fua\*(C'\fR or
\&\f(CW\*(C`next_ops\->can_fast_zero\*(C'\fR returned a positive value.
.PP
Note that unlike the plugin \f(CW\*(C`.zero\*(C'\fR which is permitted to fail with
\&\f(CW\*(C`ENOTSUP\*(C'\fR or \f(CW\*(C`EOPNOTSUPP\*(C'\fR to force a fallback to \f(CW\*(C`.pwrite\*(C'\fR, the
function \f(CW\*(C`next_ops\->zero\*(C'\fR will not fail with \f(CW\*(C`err\*(C'\fR set to
\&\f(CW\*(C`ENOTSUP\*(C'\fR or \f(CW\*(C`EOPNOTSUPP\*(C'\fR unless \f(CW\*(C`NBDKIT_FLAG_FAST_ZERO\*(C'\fR was used,
because otherwise the fallback has already taken place.
.PP
If there is an error, \f(CW\*(C`.zero\*(C'\fR should call \f(CW\*(C`nbdkit_error\*(C'\fR with an
error message \fBand\fR return \-1 with \f(CW\*(C`err\*(C'\fR set to the positive errno
value to return to the client.  The filter should not fail with
\&\f(CW\*(C`ENOTSUP\*(C'\fR or \f(CW\*(C`EOPNOTSUPP\*(C'\fR unless \f(CW\*(C`flags\*(C'\fR includes
\&\f(CW\*(C`NBDKIT_FLAG_FAST_ZERO\*(C'\fR (while plugins have automatic fallback to
\&\f(CW\*(C`.pwrite\*(C'\fR, filters do not).
.ie n .SS """.extents"""
.el .SS "\f(CW.extents\fP"
.IX Subsection ".extents"
.Vb 4
\& 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);
.Ve
.PP
This intercepts the plugin \f(CW\*(C`.extents\*(C'\fR method and can be used to
modify extent requests.
.PP
This function will not be called if \f(CW\*(C`.can_extents\*(C'\fR returned false; in
turn, the filter should not call \f(CW\*(C`next_ops\->extents\*(C'\fR if
\&\f(CW\*(C`next_ops\->can_extents\*(C'\fR did not return true.
.PP
It is possible for filters to transform the extents list received back
from the layer below.  Without error checking it would look like this:
.PP
.Vb 6
\& 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);
\& }
.Ve
.PP
If there is an error, \f(CW\*(C`.extents\*(C'\fR should call \f(CW\*(C`nbdkit_error\*(C'\fR with an
error message \fBand\fR return \-1 with \f(CW\*(C`err\*(C'\fR set to the positive errno
value to return to the client.
.PP
\fIAllocating and freeing nbdkit_extents list\fR
.IX Subsection "Allocating and freeing nbdkit_extents list"
.PP
Two functions are provided to filters only for allocating and freeing
the map:
.PP
.Vb 1
\& struct nbdkit_extents *nbdkit_extents_new (uint64_t start, uint64_t end);
.Ve
.PP
Allocates and returns a new, empty extents list.  The \f(CW\*(C`start\*(C'\fR
parameter is the start of the range described in the list, and the
\&\f(CW\*(C`end\*(C'\fR parameter is the offset of the byte beyond the end.  Normally
you would pass in \f(CW\*(C`offset\*(C'\fR 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.
.PP
On error this function can return \f(CW\*(C`NULL\*(C'\fR.  In this case it calls
\&\f(CW\*(C`nbdkit_error\*(C'\fR and/or \f(CW\*(C`nbdkit_set_error\*(C'\fR as required.  \f(CW\*(C`errno\*(C'\fR will
be set to a suitable value.
.PP
.Vb 1
\& void nbdkit_extents_free (struct nbdkit_extents *);
.Ve
.PP
Frees an existing extents list.
.PP
\fIIterating over nbdkit_extents list\fR
.IX Subsection "Iterating over nbdkit_extents list"
.PP
Two functions are provided to filters only to iterate over the extents
in order:
.PP
.Vb 1
\& size_t nbdkit_extents_count (const struct nbdkit_extents *);
.Ve
.PP
Returns the number of extents in the list.
.PP
.Vb 7
\& 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);
.Ve
.PP
Returns a copy of the \f(CW\*(C`i\*(C'\fR'th extent.
.PP
\fIEnforcing alignment of an nbdkit_extents list\fR
.IX Subsection "Enforcing alignment of an nbdkit_extents list"
.PP
A convenience function is provided to filters only which makes it
easier to ensure that the client only encounters aligned extents.
.PP
.Vb 5
\& int nbdkit_extents_aligned (struct nbdkit_next_ops *next_ops,
\&                             nbdkit_backend *nxdata,
\&                             uint32_t count, uint64_t offset,
\&                             uint32_t flags, uint32_t align,
\&                             struct nbdkit_extents *extents, int *err);
.Ve
.PP
Calls next_ops\->extents as needed until at least \f(CW\*(C`align\*(C'\fR bytes are
obtained, where \f(CW\*(C`align\*(C'\fR is a power of 2.  Anywhere the underlying
plugin returns differing extents within \f(CW\*(C`align\*(C'\fR bytes, this function
treats that portion of the disk as a single extent with zero and
sparse status bits determined by the intersection of all underlying
extents.  It is an error to call this function with \f(CW\*(C`count\*(C'\fR or
\&\f(CW\*(C`offset\*(C'\fR that is not already aligned.
.ie n .SS """.cache"""
.el .SS "\f(CW.cache\fP"
.IX Subsection ".cache"
.Vb 3
\& int (*cache) (struct nbdkit_next_ops *next_ops, void *nxdata,
\&               void *handle, uint32_t count, uint64_t offset,
\&               uint32_t flags, int *err);
.Ve
.PP
This intercepts the plugin \f(CW\*(C`.cache\*(C'\fR method and can be used to modify
cache requests.
.PP
This function will not be called if \f(CW\*(C`.can_cache\*(C'\fR returned
\&\f(CW\*(C`NBDKIT_CACHE_NONE\*(C'\fR or \f(CW\*(C`NBDKIT_CACHE_EMULATE\*(C'\fR; in turn, the filter
should not call \f(CW\*(C`next_ops\->cache\*(C'\fR unless
\&\f(CW\*(C`next_ops\->can_cache\*(C'\fR returned \f(CW\*(C`NBDKIT_CACHE_NATIVE\*(C'\fR.
.PP
The parameter \f(CW\*(C`flags\*(C'\fR exists in case of future \s-1NBD\s0 protocol
extensions; at this time, it will be 0 on input, and the filter should
not pass any flags to \f(CW\*(C`next_ops\->cache\*(C'\fR.
.PP
If there is an error, \f(CW\*(C`.cache\*(C'\fR should call \f(CW\*(C`nbdkit_error\*(C'\fR with an
error message \fBand\fR return \-1 with \f(CW\*(C`err\*(C'\fR set to the positive errno
value to return to the client.
.SH "ERROR HANDLING"
.IX Header "ERROR HANDLING"
If there is an error in the filter itself, the filter should call
\&\f(CW\*(C`nbdkit_error\*(C'\fR to report an error message.  If the callback is
involved in serving data, the explicit \f(CW\*(C`err\*(C'\fR parameter determines the
error code that will be sent to the client; other callbacks should
return the appropriate error indication, eg. \f(CW\*(C`NULL\*(C'\fR or \f(CW\*(C`\-1\*(C'\fR.
.PP
\&\f(CW\*(C`nbdkit_error\*(C'\fR has the following prototype and works like
\&\fBprintf\fR\|(3):
.PP
.Vb 2
\& void nbdkit_error (const char *fs, ...);
\& void nbdkit_verror (const char *fs, va_list args);
.Ve
.PP
For convenience, \f(CW\*(C`nbdkit_error\*(C'\fR preserves the value of \f(CW\*(C`errno\*(C'\fR, and
also supports the glibc extension of a single \f(CW%m\fR in a format string
expanding to \f(CW\*(C`strerror(errno)\*(C'\fR, even on platforms that don't support
that natively.
.SH "DEBUGGING"
.IX Header "DEBUGGING"
Run the server with \fI\-f\fR and \fI\-v\fR options so it doesn't fork and you
can see debugging information:
.PP
.Vb 1
\& nbdkit \-fv \-\-filter=./myfilter.so plugin [key=value [key=value [...]]]
.Ve
.PP
To print debugging information from within the filter, call
\&\f(CW\*(C`nbdkit_debug\*(C'\fR, which has the following prototype and works like
\&\fBprintf\fR\|(3):
.PP
.Vb 2
\& void nbdkit_debug (const char *fs, ...);
\& void nbdkit_vdebug (const char *fs, va_list args);
.Ve
.PP
For convenience, \f(CW\*(C`nbdkit_debug\*(C'\fR preserves the value of \f(CW\*(C`errno\*(C'\fR, and
also supports the glibc extension of a single \f(CW%m\fR in a format string
expanding to \f(CW\*(C`strerror(errno)\*(C'\fR, even on platforms that don't support
that natively.  Note that \f(CW\*(C`nbdkit_debug\*(C'\fR only prints things when the
server is in verbose mode (\fI\-v\fR option).
.SS "Debug Flags"
.IX Subsection "Debug Flags"
Debug Flags in filters work exactly the same way as plugins.  See
\&\*(L"Debug Flags\*(R" in \fBnbdkit\-plugin\fR\|(3).
.SH "INSTALLING THE FILTER"
.IX Header "INSTALLING THE FILTER"
The filter is a \f(CW\*(C`*.so\*(C'\fR file and possibly a manual page.  You can of
course install the filter \f(CW\*(C`*.so\*(C'\fR file wherever you want, and users
will be able to use it by running:
.PP
.Vb 1
\& nbdkit \-\-filter=/path/to/filter.so plugin [args]
.Ve
.PP
However \fBif\fR the shared library has a name of the form
\&\f(CW\*(C`nbdkit\-\f(CIname\f(CW\-filter.so\*(C'\fR \fBand if\fR the library is installed in the
\&\f(CW$filterdir\fR directory, then users can be run it by only typing:
.PP
.Vb 1
\& nbdkit \-\-filter=name plugin [args]
.Ve
.PP
The location of the \f(CW$filterdir\fR directory is set when nbdkit is
compiled and can be found by doing:
.PP
.Vb 1
\& nbdkit \-\-dump\-config
.Ve
.PP
If using the pkg\-config/pkgconf system then you can also find the
filter directory at compile time by doing:
.PP
.Vb 1
\& pkg\-config nbdkit \-\-variable=filterdir
.Ve
.SH "PKG\-CONFIG/PKGCONF"
.IX Header "PKG-CONFIG/PKGCONF"
nbdkit provides a pkg\-config/pkgconf file called \f(CW\*(C`nbdkit.pc\*(C'\fR which
should be installed on the correct path when the nbdkit development
environment is installed.  You can use this in autoconf
\&\fIconfigure.ac\fR scripts to test for the development environment:
.PP
.Vb 1
\& PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])
.Ve
.PP
The above will fail unless nbdkit ≥ 1.2.3 and the header file is
installed, and will set \f(CW\*(C`NBDKIT_CFLAGS\*(C'\fR and \f(CW\*(C`NBDKIT_LIBS\*(C'\fR
appropriately for compiling filters.
.PP
You can also run pkg\-config/pkgconf directly, for example:
.PP
.Vb 4
\& if ! pkg\-config nbdkit \-\-exists; then
\&   echo "you must install the nbdkit development environment"
\&   exit 1
\& fi
.Ve
.PP
You can also substitute the filterdir variable by doing:
.PP
.Vb 1
\& PKG_CHECK_VAR([NBDKIT_FILTERDIR], [nbdkit], [filterdir])
.Ve
.PP
which defines \f(CW\*(C`$(NBDKIT_FILTERDIR)\*(C'\fR in automake-generated Makefiles.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-plugin\fR\|(3).
.PP
Standard filters provided by nbdkit:
.PP
\&\fBnbdkit\-blocksize\-filter\fR\|(1),
\&\fBnbdkit\-cache\-filter\fR\|(1),
\&\fBnbdkit\-cacheextents\-filter\fR\|(1),
\&\fBnbdkit\-checkwrite\-filter\fR\|(1),
\&\fBnbdkit\-cow\-filter\fR\|(1),
\&\fBnbdkit\-ddrescue\-filter\fR\|(1),
\&\fBnbdkit\-delay\-filter\fR\|(1),
\&\fBnbdkit\-error\-filter\fR\|(1),
\&\fBnbdkit\-exitlast\-filter\fR\|(1),
\&\fBnbdkit\-exitwhen\-filter\fR\|(1),
\&\fBnbdkit\-exportname\-filter\fR\|(1),
\&\fBnbdkit\-ext2\-filter\fR\|(1),
\&\fBnbdkit\-extentlist\-filter\fR\|(1),
\&\fBnbdkit\-fua\-filter\fR\|(1),
\&\fBnbdkit\-gzip\-filter\fR\|(1),
\&\fBnbdkit\-ip\-filter\fR\|(1),
\&\fBnbdkit\-limit\-filter\fR\|(1),
\&\fBnbdkit\-log\-filter\fR\|(1),
\&\fBnbdkit\-nocache\-filter\fR\|(1),
\&\fBnbdkit\-noextents\-filter\fR\|(1),
\&\fBnbdkit\-nofilter\-filter\fR\|(1),
\&\fBnbdkit\-noparallel\-filter\fR\|(1),
\&\fBnbdkit\-nozero\-filter\fR\|(1),
\&\fBnbdkit\-offset\-filter\fR\|(1),
\&\fBnbdkit\-partition\-filter\fR\|(1),
\&\fBnbdkit\-pause\-filter\fR\|(1),
\&\fBnbdkit\-rate\-filter\fR\|(1),
\&\fBnbdkit\-readahead\-filter\fR\|(1),
\&\fBnbdkit\-retry\-filter\fR\|(1),
\&\fBnbdkit\-stats\-filter\fR\|(1),
\&\fBnbdkit\-swab\-filter\fR\|(1),
\&\fBnbdkit\-tar\-filter\fR\|(1),
\&\fBnbdkit\-tls\-fallback\-filter\fR\|(1),
\&\fBnbdkit\-truncate\-filter\fR\|(1),
\&\fBnbdkit\-xz\-filter\fR\|(1)
\&.
.SH "AUTHORS"
.IX Header "AUTHORS"
Eric Blake
.PP
Richard W.M. Jones
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2013\-2020 Red Hat Inc.
.SH "LICENSE"
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP "\(bu" 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP "\(bu" 4
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.
.IP "\(bu" 4
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.
.PP
\&\s-1THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS\s0 ''\s-1AS IS\s0'' \s-1AND
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\s0 (\s-1INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF
USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.\s0