filters: Adjust callback API for flags/errors
[nbdkit/ericb.git] / docs / nbdkit-filter.pod
blob8ef26e388d48f908a8a18ac250b0450c366f640a
1 =encoding utf8
3 =head1 NAME
5 nbdkit-filter - How to write nbdkit filters
7 =head1 SYNOPSIS
9  #include <nbdkit-filter.h>
11  #define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL
13  static int
14  myfilter_config (nbdkit_next_config *next, void *nxdata,
15                   const char *key, const char *value)
16  {
17    if (strcmp (key, "myparameter") == 0) {
18      // ...
19      return 0;
20    }
21    else {
22      // pass through to next filter or plugin
23      return next (nxdata, key, value);
24    }
25  }
27  static struct nbdkit_filter filter = {
28    .name              = "filter",
29    .config            = myfilter_config,
30    /* etc */
31  };
33  NBDKIT_REGISTER_FILTER(filter)
35 When this has been compiled to a shared library, do:
37  nbdkit [--args ...] --filter=./myfilter.so plugin [key=value ...]
39 When debugging, use the I<-fv> options:
41  nbdkit -fv --filter=./myfilter.so plugin [key=value ...]
43 =head1 DESCRIPTION
45 One or more nbdkit filters can be placed in front of an nbdkit plugin
46 to modify the behaviour of the plugin.  This manual page describes how
47 to create an nbdkit filter.
49 Filters can be used for example to limit requests to an offset/limit,
50 add copy-on-write support, or inject delays or errors (for testing).
52 Different filters can be stacked:
54      NBD     ┌─────────┐    ┌─────────┐          ┌────────┐
55   client ───▶│ filter1 │───▶│ filter2 │── ─ ─ ──▶│ plugin │
56  request     └─────────┘    └─────────┘          └────────┘
58 Each filter intercepts plugin functions (see L<nbdkit-plugin(3)>) and
59 can call the next filter or plugin in the chain, modifying parameters,
60 calling before the filter function, in the middle or after.  Filters
61 may even short-cut the chain.  As an example, to process its own
62 parameters the filter can intercept the C<.config> method:
64  static int
65  myfilter_config (nbdkit_next_config *next, void *nxdata,
66                   const char *key, const char *value)
67  {
68    if (strcmp (key, "myparameter") == 0) {
69      // ...
70      // here you would handle this key, value
71      // ...
72      return 0;
73    }
74    else {
75      // pass through to next filter or plugin
76      return next (nxdata, key, value);
77    }
78  }
80  static struct nbdkit_filter filter = {
81    // ...
82    .config            = myfilter_config,
83    // ...
84  };
86 The call to C<next (nxdata, ...)> calls the C<.config> method of the
87 next filter or plugin in the chain.  In the example above any
88 instances of C<myparameter=...> on the command line would not be seen
89 by the plugin.
91 To see example filters, take a look at the source of nbdkit, in the
92 C<filters> directory.
94 Filters must be written in C.
96 Unlike plugins, where we provide a stable ABI guarantee that permits
97 operation across version differences, filters can only be run with the
98 same version of nbdkit that they were compiled with.  The reason for
99 this is two-fold: the filter API includes access to struct
100 nbdkit_next_ops that is likely to change if new callbacks are added
101 (old nbdkit cannot safely run new filters that access new methods);
102 and if we added new methods then an old filter would not see them and
103 so they would be passed unmodified through the filter, and in some
104 cases that leads to data corruption (new nbdkit cannot safely run old
105 filters unaware of new methods).  Therefore, unlike plugins, you
106 should not expect to distribute filters separately from nbdkit.
108 =head1 C<nbdkit-filter.h>
110 All filters should start by including this header file:
112  #include <nbdkit-filter.h>
114 =head1 C<#define THREAD_MODEL>
116 All filters must define a thread model.  See
117 L<nbdkit-plugin(3)/THREADS> for a discussion of thread models.
119 The final thread model is the smallest (ie. most serialized) out of
120 all the filters and the plugin.  Filters cannot alter the thread model
121 to make it larger (more parallel).
123 If possible filters should be be written to handle fully parallel
124 requests (C<NBDKIT_THREAD_MODEL_PARALLEL>, even multiple requests
125 issued in parallel on the same connection).  This ensures that they
126 don't slow down other filters or plugins.
128 =head1 C<struct nbdkit_filter>
130 All filters must define and register one C<struct nbdkit_filter>,
131 which contains the name of the filter and pointers to plugin methods
132 that the filter wants to intercept.
134  static struct nbdkit_filter filter = {
135    .name              = "filter",
136    .longname          = "My Filter",
137    .description       = "This is my great filter for nbdkit",
138    .config            = myfilter_config,
139    /* etc */
140  };
142  NBDKIT_REGISTER_FILTER(filter)
144 The C<.name> field is the name of the filter.  This is the only field
145 which is required.
147 =head1 NEXT PLUGIN
149 F<nbdkit-filter.h> defines three function types
150 (C<nbdkit_next_config>, C<nbdkit_next_config_complete>,
151 C<nbdkit_next_open>) and a structure called C<struct nbdkit_next_ops>.
152 These abstract the next plugin or filter in the chain.  There is also
153 an opaque pointer C<nxdata> which must be passed along when calling
154 these functions.
156 The filter’s C<.config>, C<.config_complete> and C<.open> methods may
157 only call the next C<.config>, C<.config_complete> and C<.open> method
158 in the chain (optionally for C<.config>).
160 The filter’s C<.close> method is called when an old connection closed,
161 and this has no C<next> parameter because it cannot be
162 short-circuited.
164 The filter’s other methods like C<.prepare>, C<.get_size>, C<.pread>
165 etc ― always called in the context of a connection ― are passed a
166 pointer to C<struct nbdkit_next_ops> which contains a comparable set
167 of accessors to plugin methods that can be called during a connection.
168 It is possible for a filter to issue (for example) extra read calls in
169 response to a single C<.pwrite> call.  Note that the semantics of the
170 functions in C<struct nbdkit_next_ops> are slightly different from
171 what a plugin implements: for example, when a plugin's C<.pread>
172 returns -1 on error, the error value to advertise to the client is
173 implicit (via the plugin calling C<nbdkit_set_error> or setting
174 C<errno>), whereas C<next_ops-E<gt>pread> exposes this via an explicit
175 parameter, allowing a filter to learn or modify this error if desired.
177 You can modify parameters when you call the C<next> function.  However
178 be careful when modifying strings because for some methods
179 (eg. C<.config>) the plugin may save the string pointer that you pass
180 along.  So you may have to ensure that the string is not freed for the
181 lifetime of the server.
183 Note that if your filter registers a callback but in that callback it
184 doesn't call the C<next> function then the corresponding method in the
185 plugin will never be called.  In particular, your C<.open> method, if
186 you have one, B<must> call the C<.next> method.
188 =head1 CALLBACKS
190 C<struct nbdkit_filter> has some static fields describing the filter
191 and optional callback functions which can be used to intercept plugin
192 methods.
194 =head2 C<.name>
196  const char *name;
198 This field (a string) is required, and B<must> contain only ASCII
199 alphanumeric characters and be unique amongst all filters.
201 =head2 C<.version>
203  const char *version;
205 Filters may optionally set a version string which is displayed in help
206 and debugging output.
208 =head2 C<.longname>
210  const char *longname;
212 An optional free text name of the filter.  This field is used in error
213 messages.
215 =head2 C<.description>
217  const char *description;
219 An optional multi-line description of the filter.
221 =head2 C<.load>
223  void load (void);
225 This is called once just after the filter is loaded into memory.  You
226 can use this to perform any global initialization needed by the
227 filter.
229 =head2 C<.unload>
231  void unload (void);
233 This may be called once just before the filter is unloaded from
234 memory.  Note that it's not guaranteed that C<.unload> will always be
235 called (eg. the server might be killed or segfault), so you should try
236 to make the filter as robust as possible by not requiring cleanup.
237 See also L<nbdkit-plugin(3)/SHUTDOWN>.
239 =head2 C<.config>
241  int (*config) (nbdkit_next_config *next, void *nxdata,
242                 const char *key, const char *value);
244 This intercepts the plugin C<.config> method and can be used by the
245 filter to parse its own command line parameters.  You should try to
246 make sure that command line parameter keys that the filter uses do not
247 conflict with ones that could be used by a plugin.
249 If there is an error, C<.config> should call C<nbdkit_error> with an
250 error message and return C<-1>.
252 =head2 C<.config_complete>
254  int (*config_complete) (nbdkit_next_config_complete *next, void *nxdata);
256 This intercepts the plugin C<.config_complete> method and can be used
257 to ensure that all parameters needed by the filter were supplied on
258 the command line.
260 If there is an error, C<.config_complete> should call C<nbdkit_error>
261 with an error message and return C<-1>.
263 =head2 C<.config_help>
265  const char *config_help;
267 This optional multi-line help message should summarize any
268 C<key=value> parameters that it takes.  It does I<not> need to repeat
269 what already appears in C<.description>.
271 If the filter doesn't take any config parameters you should probably
272 omit this.
274 =head2 C<.open>
276  void * (*open) (nbdkit_next_open *next, void *nxdata,
277                  int readonly);
279 This is called when a new client connection is opened and can be used
280 to allocate any per-connection data structures needed by the filter.
281 The handle (which is not the same as the plugin handle) is passed back
282 to other filter callbacks and could be freed in the C<.close>
283 callback.
285 Note that the handle is completely opaque to nbdkit, but it must not
286 be NULL.
288 If there is an error, C<.open> should call C<nbdkit_error> with an
289 error message and return C<NULL>.
291 =head2 C<.close>
293  void (*close) (void *handle);
295 This is called when the client closes the connection.  It should clean
296 up any per-connection resources used by the filter.
298 =head2 C<.prepare>
300 =head2 C<.finalize>
302   int (*prepare) (struct nbdkit_next_ops *next_ops, void *nxdata,
303                   void *handle);
304   int (*finalize) (struct nbdkit_next_ops *next_ops, void *nxdata,
305                    void *handle);
307 These two methods can be used to perform any necessary operations just
308 after opening the connection (C<.prepare>) or just before closing the
309 connection (C<.finalize>).
311 For example if you need to scan the underlying disk to check for a
312 partition table, you could do it in your C<.prepare> method (calling
313 the plugin's C<.pread> method via C<next_ops>).  Or if you need to
314 cleanly update superblock data in the image on close you can do it in
315 your C<.finalize> method (calling the plugin's C<.pwrite> method).
316 Doing these things in the filter's C<.open> or C<.close> method is not
317 possible.
319 If there is an error, both callbacks should call C<nbdkit_error> with
320 an error message and return C<-1>.
322 =head2 C<.get_size>
324  int64_t (*get_size) (struct nbdkit_next_ops *next_ops, void *nxdata,
325                       void *handle);
327 This intercepts the plugin C<.get_size> method and can be used to read
328 or modify the apparent size of the block device that the NBD client
329 will see.
331 The returned size must be E<ge> 0.  If there is an error, C<.get_size>
332 should call C<nbdkit_error> with an error message and return C<-1>.
333 If this function is called more than once for the same connection, it
334 should return the same value; similarly, the filter may cache
335 C<next_ops-E<gt>get_size> for a given connection rather than repeating
336 calls.
338 =head2 C<.can_write>
340 =head2 C<.can_flush>
342 =head2 C<.is_rotational>
344 =head2 C<.can_trim>
346  int (*can_write) (struct nbdkit_next_ops *next_ops, void *nxdata,
347                    void *handle);
348  int (*can_flush) (struct nbdkit_next_ops *next_ops, void *nxdata,
349                    void *handle);
350  int (*is_rotational) (struct nbdkit_next_ops *next_ops,
351                        void *nxdata,
352                        void *handle);
353  int (*can_trim) (struct nbdkit_next_ops *next_ops, void *nxdata,
354                   void *handle);
356 These intercept the corresponding plugin methods.
358 If there is an error, the callback should call C<nbdkit_error> with an
359 error message and return C<-1>.  If these functions are called more
360 than once for the same connection, they should return the same value;
361 similarly, the filter may cache the results of each counterpart in
362 C<next_ops> for a given connection rather than repeating calls.
364 =head2 C<.pread>
366  int (*pread) (struct nbdkit_next_ops *next_ops, void *nxdata,
367                void *handle, void *buf, uint32_t count, uint64_t offset,
368                uint32_t flags, int *err);
370 This intercepts the plugin C<.pread> method and can be used to read or
371 modify data read by the plugin.
373 The parameter C<flags> exists in case of future NBD protocol
374 extensions; at this time, it will be 0 on input, and the filter should
375 not pass any flags to C<next_ops-E<gt>pread>.
377 If there is an error (including a short read which couldn't be
378 recovered from), C<.pread> should call C<nbdkit_error> with an error
379 message B<and> return -1 with C<err> set to the positive errno value
380 to return to the client.
382 =head2 C<.pwrite>
384  int (*pwrite) (struct nbdkit_next_ops *next_ops, void *nxdata,
385                 void *handle,
386                 const void *buf, uint32_t count, uint64_t offset,
387                 uint32_t flags, int *err);
389 This intercepts the plugin C<.pwrite> method and can be used to modify
390 data written by the plugin.
392 This function will not be called if C<.can_write> returned false; in
393 turn, the filter should not call C<next_ops-E<gt>pwrite> if
394 C<next_ops-E<gt>can_write> did not return true.
396 The parameter C<flags> may include C<NBDKIT_FLAG_FUA> on input based
397 on the result of C<.can_flush>.  In turn, the filter should only pass
398 C<NBDKIT_FLAG_FUA> on to C<next_ops-E<gt>pwrite> if
399 C<next_ops-E<gt>can_flush> returned true.
401 If there is an error (including a short write which couldn't be
402 recovered from), C<.pwrite> should call C<nbdkit_error> with an error
403 message B<and> return -1 with C<err> set to the positive errno value
404 to return to the client.
406 =head2 C<.flush>
408  int (*flush) (struct nbdkit_next_ops *next_ops, void *nxdata,
409                void *handle, uint32_t flags, int *err);
411 This intercepts the plugin C<.flush> method and can be used to modify
412 flush requests.
414 This function will not be called if C<.can_flush> returned false; in
415 turn, the filter should not call C<next_ops-E<gt>flush> if
416 C<next_ops-E<gt>can_flush> did not return true.
418 The parameter C<flags> exists in case of future NBD protocol
419 extensions; at this time, it will be 0 on input, and the filter should
420 not pass any flags to C<next_ops-E<gt>flush>.
422 If there is an error, C<.flush> should call C<nbdkit_error> with an
423 error message B<and> return -1 with C<err> set to the positive errno
424 value to return to the client.
426 =head2 C<.trim>
428  int (*trim) (struct nbdkit_next_ops *next_ops, void *nxdata,
429               void *handle, uint32_t count, uint64_t offset,
430               uint32_t flags, int *err);
432 This intercepts the plugin C<.trim> method and can be used to modify
433 trim requests.
435 This function will not be called if C<.can_trim> returned false; in
436 turn, the filter should not call C<next_ops-E<gt>trim> if
437 C<next_ops-E<gt>can_trim> did not return true.
439 The parameter C<flags> may include C<NBDKIT_FLAG_FUA> on input based
440 on the result of C<.can_flush>.  In turn, the filter should only pass
441 C<NBDKIT_FLAG_FUA> on to C<next_ops-E<gt>trim> if
442 C<next_ops-E<gt>can_flush> returned true.
444 If there is an error, C<.trim> should call C<nbdkit_error> with an
445 error message B<and> return -1 with C<err> set to the positive errno
446 value to return to the client.
448 =head2 C<.zero>
450  int (*zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
451               void *handle, uint32_t count, uint64_t offset, uint32_t flags,
452               int *err);
454 This intercepts the plugin C<.zero> method and can be used to modify
455 zero requests.
457 This function will not be called if C<.can_write> returned false; in
458 turn, the filter should not call C<next_ops-E<gt>zero> if
459 C<next_ops-E<gt>can_write> did not return true.
461 On input, the parameter C<flags> may include C<NBDKIT_FLAG_MAY_TRIM>
462 unconditionally, and C<NBDKIT_FLAG_FUA> based on the result of
463 C<.can_flush>.  In turn, the filter may pass C<NBDKIT_FLAG_MAY_TRIM>
464 unconditionally, but should only pass C<NBDKIT_FLAG_FUA> on to
465 C<next_ops-E<gt>zero> if C<next_ops-E<gt>can_flush> returned true.
467 Note that unlike the plugin C<.zero> which is permitted to fail with
468 C<EOPNOTSUPP> to force a fallback to C<.pwrite>, the function
469 C<next_ops-E<gt>zero> will never fail with C<err> set to C<EOPNOTSUPP>
470 because the fallback has already taken place.
472 If there is an error, C<.zero> should call C<nbdkit_error> with an
473 error message B<and> return -1 with C<err> set to the positive errno
474 value to return to the client.  The filter should never fail with
475 C<EOPNOTSUPP> (while plugins have automatic fallback to C<.pwrite>,
476 filters do not).
478 =head1 ERROR HANDLING
480 If there is an error in the filter itself, the filter should call
481 C<nbdkit_error> to report an error message.  If the callback is
482 involved in serving data, the explicit C<err> parameter determines the
483 error code that will be sent to the client; other callbacks should
484 return the appropriate error indication, eg. C<NULL> or C<-1>.
486 C<nbdkit_error> has the following prototype and works like
487 L<printf(3)>:
489  void nbdkit_error (const char *fs, ...);
490  void nbdkit_verror (const char *fs, va_list args);
492 For convenience, C<nbdkit_error> preserves the value of C<errno>.
494 =head1 DEBUGGING
496 Run the server with I<-f> and I<-v> options so it doesn't fork and you
497 can see debugging information:
499  nbdkit -fv --filter=./myfilter.so plugin [key=value [key=value [...]]]
501 To print debugging information from within the filter, call
502 C<nbdkit_debug>, which has the following prototype and works like
503 L<printf(3)>:
505  void nbdkit_debug (const char *fs, ...);
506  void nbdkit_vdebug (const char *fs, va_list args);
508 For convenience, C<nbdkit_debug> preserves the value of C<errno>.
509 Note that C<nbdkit_debug> only prints things when the server is in
510 verbose mode (I<-v> option).
512 =head1 INSTALLING THE FILTER
514 The filter is a C<*.so> file and possibly a manual page.  You can of
515 course install the filter C<*.so> file wherever you want, and users
516 will be able to use it by running:
518  nbdkit --filter=/path/to/filter.so plugin [args]
520 However B<if> the shared library has a name of the form
521 C<nbdkit-I<name>-filter.so> B<and if> the library is installed in the
522 C<$filterdir> directory, then users can be run it by only typing:
524  nbdkit --filter=name plugin [args]
526 The location of the C<$filterdir> directory is set when nbdkit is
527 compiled and can be found by doing:
529  nbdkit --dump-config
531 If using the pkg-config/pkgconf system then you can also find the
532 filter directory at compile time by doing:
534  pkgconf nbdkit --variable=filterdir
536 =head1 PKG-CONFIG/PKGCONF
538 nbdkit provides a pkg-config/pkgconf file called C<nbdkit.pc> which
539 should be installed on the correct path when the nbdkit development
540 environment is installed.  You can use this in autoconf
541 F<configure.ac> scripts to test for the development environment:
543  PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])
545 The above will fail unless nbdkit E<ge> 1.2.3 and the header file is
546 installed, and will set C<NBDKIT_CFLAGS> and C<NBDKIT_LIBS>
547 appropriately for compiling filters.
549 You can also run pkg-config/pkgconf directly, for example:
551  if ! pkgconf nbdkit --exists; then
552    echo "you must install the nbdkit development environment"
553    exit 1
554  fi
556 =head1 SEE ALSO
558 L<nbdkit(1)>,
559 L<nbdkit-plugin(1)>.
561 Filters:
563 L<nbdkit-cache-filter(1)>,
564 L<nbdkit-cow-filter(1)>,
565 L<nbdkit-delay-filter(1)>,
566 L<nbdkit-offset-filter(1)>,
567 L<nbdkit-partition-filter(1)>.
569 =head1 AUTHORS
571 Richard W.M. Jones
573 =head1 COPYRIGHT
575 Copyright (C) 2013-2018 Red Hat Inc.
577 =head1 LICENSE
579 Redistribution and use in source and binary forms, with or without
580 modification, are permitted provided that the following conditions are
581 met:
583 =over 4
585 =item *
587 Redistributions of source code must retain the above copyright
588 notice, this list of conditions and the following disclaimer.
590 =item *
592 Redistributions in binary form must reproduce the above copyright
593 notice, this list of conditions and the following disclaimer in the
594 documentation and/or other materials provided with the distribution.
596 =item *
598 Neither the name of Red Hat nor the names of its contributors may be
599 used to endorse or promote products derived from this software without
600 specific prior written permission.
602 =back
604 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND
605 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
606 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
607 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
608 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
609 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
610 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
611 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
612 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
613 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
614 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
615 SUCH DAMAGE.