3 nbdkit-filter - how to write nbdkit filters
7 #include <nbdkit-filter.h>
10 myfilter_config (nbdkit_next_config *next, void *nxdata,
11 const char *key, const char *value)
13 if (strcmp (key, "myparameter") == 0) {
18 // pass through to next filter or plugin
19 return next (nxdata, key, value);
23 static struct nbdkit_filter filter = {
25 .config = myfilter_config,
29 NBDKIT_REGISTER_FILTER(filter)
31 When this has been compiled to a shared library, do:
33 nbdkit [--args ...] --filter=./myfilter.so plugin [key=value ...]
35 When debugging, use the I<-fv> options:
37 nbdkit -fv --filter=./myfilter.so plugin [key=value ...]
41 One or more nbdkit filters can be placed in front of an nbdkit plugin
42 to modify the behaviour of the plugin. This manual page describes how
43 to create an nbdkit filter.
45 Filters can be used for example to limit requests to an offset/limit,
46 add copy-on-write support, or inject delays or errors (for testing).
48 Different filters can be stacked:
50 NBD ┌─────────┐ ┌─────────┐ ┌────────┐
51 client ───▶│ filter1 │───▶│ filter2 │── ─ ─ ──▶│ plugin │
52 request └─────────┘ └─────────┘ └────────┘
54 Each filter intercepts plugin functions (see L<nbdkit-plugin(3)>) and
55 can call the next filter or plugin in the chain, modifying parameters,
56 calling before the filter function, in the middle or after. Filters
57 may even short-cut the chain. As an example, to process its own
58 parameters the filter can intercept the C<.config> method:
61 myfilter_config (nbdkit_next_config *next, void *nxdata,
62 const char *key, const char *value)
64 if (strcmp (key, "myparameter") == 0) {
66 // here you would handle this key, value
71 // pass through to next filter or plugin
72 return next (nxdata, key, value);
76 static struct nbdkit_filter filter = {
78 .config = myfilter_config,
82 The call to C<next (nxdata, ...)> calls the C<.config> method of the
83 next filter or plugin in the chain. In the example above any
84 instances of C<myparameter=...> on the command line would not be seen
87 To see example filters:
88 L<https://github.com/libguestfs/nbdkit/tree/master/filters>
90 Filters must be written in C.
92 Unlike plugins, where we provide a stable ABI guarantee that permits
93 operation across version differences, filters can only be run with the
94 same version of nbdkit that they were compiled with. The reason for
95 this is two-fold: the filter API includes access to struct
96 nbdkit_next_ops that is likely to change if new callbacks are added
97 (old nbdkit cannot safely run new filters that access new methods);
98 and if we added new methods then an old filter would not see them and
99 so they would be passed unmodified through the filter, and in some
100 cases that leads to data corruption (new nbdkit cannot safely run old
101 filters unaware of new methods). Therefore, unlike plugins, you
102 should not expect to distribute filters separately from nbdkit.
104 =head1 C<#include E<lt>nbdkit-filter.hE<gt>>
106 All filters should start by including this header file.
108 =head1 C<struct nbdkit_filter>
110 All filters must define and register one C<struct nbdkit_filter>,
111 which contains the name of the filter and pointers to plugin methods
112 that the filter wants to intercept.
114 static struct nbdkit_filter filter = {
116 .longname = "My Filter",
117 .description = "This is my great filter for nbdkit",
118 .config = myfilter_config,
122 NBDKIT_REGISTER_FILTER(filter)
124 The C<.name> field is the name of the filter. This is the only field
129 F<nbdkit-filter.h> defines some function types (C<nbdkit_next_config>,
130 C<nbdkit_next_config_complete>, C<nbdkit_next_preconnect>,
131 C<nbdkit_next_open>) and a structure called C<struct nbdkit_next_ops>.
132 These abstract the next plugin or filter in the chain. There is also
133 an opaque pointer C<nxdata> which must be passed along when calling
136 =head2 Next config, open and close
138 The filter’s C<.config>, C<.config_complete> and C<.open> methods may
139 only call the next C<.config>, C<.config_complete> and C<.open> method
140 in the chain (optionally for C<.config>).
142 The filter’s C<.close> method is called when an old connection closed,
143 and this has no C<next> parameter because it cannot be
148 The filter’s other methods like C<.prepare>, C<.get_size>, C<.pread>
149 etc ― always called in the context of a connection ― are passed a
150 pointer to C<struct nbdkit_next_ops> which contains a comparable set
151 of accessors to plugin methods that can be called during a connection.
153 It is possible for a filter to issue (for example) extra
154 C<next_ops-E<gt>pread> calls in response to a single C<.pwrite> call.
156 Note that the semantics of the functions in C<struct nbdkit_next_ops>
157 are slightly different from what a plugin implements: for example,
158 when a plugin's C<.pread> returns -1 on error, the error value to
159 advertise to the client is implicit (via the plugin calling
160 C<nbdkit_set_error> or setting C<errno>), whereas
161 C<next_ops-E<gt>pread> exposes this via an explicit parameter,
162 allowing a filter to learn or modify this error if desired.
164 There is also a C<next_ops-E<gt>reopen> function which is used by
165 L<nbdkit-retry-filter(3)> to close and reopen the underlying plugin.
166 It should be used with caution because it is difficult to use safely.
168 =head2 Other considerations
170 You can modify parameters when you call the C<next> function. However
171 be careful when modifying strings because for some methods
172 (eg. C<.config>) the plugin may save the string pointer that you pass
173 along. So you may have to ensure that the string is not freed for the
174 lifetime of the server.
176 Note that if your filter registers a callback but in that callback it
177 doesn't call the C<next> function then the corresponding method in the
178 plugin will never be called. In particular, your C<.open> method, if
179 you have one, B<must> call the C<.next> method.
183 C<struct nbdkit_filter> has some static fields describing the filter
184 and optional callback functions which can be used to intercept plugin
191 This field (a string) is required, and B<must> contain only ASCII
192 alphanumeric characters and be unique amongst all filters.
196 const char *longname;
198 An optional free text name of the filter. This field is used in error
201 =head2 C<.description>
203 const char *description;
205 An optional multi-line description of the filter.
211 This is called once just after the filter is loaded into memory. You
212 can use this to perform any global initialization needed by the
219 This may be called once just before the filter is unloaded from
220 memory. Note that it's not guaranteed that C<.unload> will always be
221 called (eg. the server might be killed or segfault), so you should try
222 to make the filter as robust as possible by not requiring cleanup.
223 See also L<nbdkit-plugin(3)/SHUTDOWN>.
227 int (*config) (nbdkit_next_config *next, void *nxdata,
228 const char *key, const char *value);
230 This intercepts the plugin C<.config> method and can be used by the
231 filter to parse its own command line parameters. You should try to
232 make sure that command line parameter keys that the filter uses do not
233 conflict with ones that could be used by a plugin.
235 If there is an error, C<.config> should call C<nbdkit_error> with an
236 error message and return C<-1>.
238 =head2 C<.config_complete>
240 int (*config_complete) (nbdkit_next_config_complete *next, void *nxdata);
242 This intercepts the plugin C<.config_complete> method and can be used
243 to ensure that all parameters needed by the filter were supplied on
246 If there is an error, C<.config_complete> should call C<nbdkit_error>
247 with an error message and return C<-1>.
249 =head2 C<.config_help>
251 const char *config_help;
253 This optional multi-line help message should summarize any
254 C<key=value> parameters that it takes. It does I<not> need to repeat
255 what already appears in C<.description>.
257 If the filter doesn't take any config parameters you should probably
260 =head2 C<.thread_model>
262 int (*thread_model) (void);
264 Filters may tighten (but not relax) the thread model of the plugin, by
265 defining this callback. Note that while plugins use a compile-time
266 definition of C<THREAD_MODEL>, filters do not need to declare a model
267 at compile time; instead, this callback is called after
268 C<.config_complete> and before any connections are created. See
269 L<nbdkit-plugin(3)/THREADS> for a discussion of thread models.
271 The final thread model used by nbdkit is the smallest (ie. most
272 serialized) out of all the filters and the plugin, and applies for all
273 connections. Requests for a model larger than permitted by the plugin
274 are silently ignored. It is acceptable for decisions made during
275 C<.config> and C<.config_complete> to determine which model to
278 This callback is optional; if it is not present, the filter must be
279 written to handle fully parallel requests, including when multiple
280 requests are issued in parallel on the same connection, similar to a
281 plugin requesting C<NBDKIT_THREAD_MODEL_PARALLEL>. This ensures the
282 filter doesn't slow down other filters or plugins.
284 If there is an error, C<.thread_model> should call C<nbdkit_error>
285 with an error message and return C<-1>.
287 =head2 C<.preconnect>
289 int (*preconnect) (nbdkit_next_preconnect *next, void *nxdata,
292 This intercepts the plugin C<.preconnect> method and can be used to
293 filter access to the server.
295 If there is an error, C<.preconnect> should call C<nbdkit_error> with
296 an error message and return C<-1>.
300 void * (*open) (nbdkit_next_open *next, void *nxdata,
303 This is called when a new client connection is opened and can be used
304 to allocate any per-connection data structures needed by the filter.
305 The handle (which is not the same as the plugin handle) is passed back
306 to other filter callbacks and could be freed in the C<.close>
309 Note that the handle is completely opaque to nbdkit, but it must not
310 be NULL. If you don't need to use a handle, return
311 C<NBDKIT_HANDLE_NOT_NEEDED> which is a static non-NULL pointer.
313 If there is an error, C<.open> should call C<nbdkit_error> with an
314 error message and return C<NULL>.
316 This callback is optional, but if provided, it must call C<next>,
317 passing a value for C<readonly> according to how the filter plans to
318 use the plugin. Typically, the filter passes the same value as it
319 received, or passes true to provide a writable layer on top of a
320 read-only backend. However, it is also acceptable to attempt write
321 access to the plugin even if this filter is readonly, such as when a
322 file system mounted read-only still requires write access to the
323 underlying device in case a journal needs to be replayed for
324 consistency as part of the mounting process. The filter should
325 generally call C<next> as its first step, to allocate from the plugin
326 outwards, so that C<.close> running from the outer filter to the
327 plugin will be in reverse.
331 void (*close) (void *handle);
333 This is called when the client closes the connection. It should clean
334 up any per-connection resources used by the filter. It is called
335 beginning with the outermost filter and ending with the plugin (the
336 opposite order of C<.open> if all filters call C<next> first),
337 although this order technically does not matter since the callback
338 cannot report failures or access the underlying plugin.
344 int (*prepare) (struct nbdkit_next_ops *next_ops, void *nxdata,
345 void *handle, int readonly);
346 int (*finalize) (struct nbdkit_next_ops *next_ops, void *nxdata,
349 These two methods can be used to perform any necessary operations just
350 after opening the connection (C<.prepare>) or just before closing the
351 connection (C<.finalize>).
353 For example if you need to scan the underlying disk to check for a
354 partition table, you could do it in your C<.prepare> method (calling
355 the plugin's C<.pread> method via C<next_ops>). Or if you need to
356 cleanly update superblock data in the image on close you can do it in
357 your C<.finalize> method (calling the plugin's C<.pwrite> method).
358 Doing these things in the filter's C<.open> or C<.close> method is not
361 For C<.prepare>, the value of C<readonly> is the same as was passed to
362 C<.open>, declaring how this filter will be used.
364 There is no C<next_ops-E<gt>prepare> or C<next_ops-E<gt>finalize>.
365 Unlike other filter methods, prepare and finalize are not chained
366 through the C<next_ops> structure. Instead the core nbdkit server
367 calls the prepare and finalize methods of all filters. Prepare
368 methods are called starting with the filter closest to the plugin and
369 proceeding outwards (matching the order of C<.open> if all filters
370 call C<next> before doing anything locally). Finalize methods are
371 called in the reverse order of prepare methods, with the outermost
372 filter first (and matching the order of C<.close>), and only if the
373 prepare method succeeded.
375 If there is an error, both callbacks should call C<nbdkit_error> with
376 an error message and return C<-1>. An error in C<.prepare> is
377 reported to the client, but leaves the connection open (a client may
378 try again with a different export name, for example); while an error
379 in C<.finalize> forces the client to disconnect.
383 int64_t (*get_size) (struct nbdkit_next_ops *next_ops, void *nxdata,
386 This intercepts the plugin C<.get_size> method and can be used to read
387 or modify the apparent size of the block device that the NBD client
390 The returned size must be E<ge> 0. If there is an error, C<.get_size>
391 should call C<nbdkit_error> with an error message and return C<-1>.
392 This function is only called once per connection and cached by nbdkit.
393 Similarly, repeated calls to C<next_ops-E<gt>get_size> will return a
400 =head2 C<.is_rotational>
406 =head2 C<.can_fast_zero>
408 =head2 C<.can_extents>
412 =head2 C<.can_multi_conn>
416 =head2 C<.init_sparse>
420 int (*can_write) (struct nbdkit_next_ops *next_ops, void *nxdata,
422 int (*can_flush) (struct nbdkit_next_ops *next_ops, void *nxdata,
424 int (*is_rotational) (struct nbdkit_next_ops *next_ops,
427 int (*can_trim) (struct nbdkit_next_ops *next_ops, void *nxdata,
429 int (*can_zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
431 int (*can_fast_zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
433 int (*can_extents) (struct nbdkit_next_ops *next_ops, void *nxdata,
435 int (*can_fua) (struct nbdkit_next_ops *next_ops, void *nxdata,
437 int (*can_multi_conn) (struct nbdkit_next_ops *next_ops, void *nxdata,
439 int (*can_cache) (struct nbdkit_next_ops *next_ops, void *nxdata,
441 int (*init_sparse) (struct nbdkit_next_ops *next_ops, void *nxdata,
443 int (*init_zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
446 These intercept the corresponding plugin methods, and control feature
447 bits advertised to the client.
449 Of note, the semantics of C<.can_zero> callback in the filter are
450 slightly different from the plugin, and must be one of three success
451 values visible only to filters:
455 =item C<NBDKIT_ZERO_NONE>
457 Completely suppress advertisement of write zero support (this can only
458 be done from filters, not plugins).
460 =item C<NBDKIT_ZERO_EMULATE>
462 Inform nbdkit that write zeroes should immediately fall back to
463 C<.pwrite> emulation without trying C<.zero> (this value is returned
464 by C<next_ops-E<gt>can_zero> if the plugin returned false in its
467 =item C<NBDKIT_ZERO_NATIVE>
469 Inform nbdkit that write zeroes should attempt to use C<.zero>,
470 although it may still fall back to C<.pwrite> emulation for C<ENOTSUP>
471 or C<EOPNOTSUPP> failures (this value is returned by
472 C<next_ops-E<gt>can_zero> if the plugin returned true in its
477 Remember that most of the feature check functions return merely a
478 boolean success value, while C<.can_zero>, C<.can_fua> and
479 C<.can_cache> have three success values.
481 The difference between C<.can_fua> values may affect choices made in
482 the filter: when splitting a write request that requested FUA from the
483 client, if C<next_ops-E<gt>can_fua> returns C<NBDKIT_FUA_NATIVE>, then
484 the filter should pass the FUA flag on to each sub-request; while if
485 it is known that FUA is emulated by a flush because of a return of
486 C<NBDKIT_FUA_EMULATE>, it is more efficient to only flush once after
487 all sub-requests have completed (often by passing C<NBDKIT_FLAG_FUA>
488 on to only the final sub-request, or by dropping the flag and ending
489 with a direct call to C<next_ops-E<gt>flush>).
491 If there is an error, the callback should call C<nbdkit_error> with an
492 error message and return C<-1>. These functions are called at most
493 once per connection and cached by nbdkit. Similarly, repeated calls to
494 any of the C<next_ops> counterparts will return a cached value; by
495 calling into the plugin during C<.prepare>, you can ensure that later
496 use of the cached values during data commands like <.pwrite> will not
501 int (*pread) (struct nbdkit_next_ops *next_ops, void *nxdata,
502 void *handle, void *buf, uint32_t count, uint64_t offset,
503 uint32_t flags, int *err);
505 This intercepts the plugin C<.pread> method and can be used to read or
506 modify data read by the plugin.
508 The parameter C<flags> exists in case of future NBD protocol
509 extensions; at this time, it will be 0 on input, and the filter should
510 not pass any flags to C<next_ops-E<gt>pread>.
512 If there is an error (including a short read which couldn't be
513 recovered from), C<.pread> should call C<nbdkit_error> with an error
514 message B<and> return -1 with C<err> set to the positive errno value
515 to return to the client.
519 int (*pwrite) (struct nbdkit_next_ops *next_ops, void *nxdata,
521 const void *buf, uint32_t count, uint64_t offset,
522 uint32_t flags, int *err);
524 This intercepts the plugin C<.pwrite> method and can be used to modify
525 data written by the plugin.
527 This function will not be called if C<.can_write> returned false; in
528 turn, the filter should not call C<next_ops-E<gt>pwrite> if
529 C<next_ops-E<gt>can_write> did not return true.
531 The parameter C<flags> may include C<NBDKIT_FLAG_FUA> on input based
532 on the result of C<.can_fua>. In turn, the filter should only pass
533 C<NBDKIT_FLAG_FUA> on to C<next_ops-E<gt>pwrite> if
534 C<next_ops-E<gt>can_fua> returned a positive value.
536 If there is an error (including a short write which couldn't be
537 recovered from), C<.pwrite> should call C<nbdkit_error> with an error
538 message B<and> return -1 with C<err> set to the positive errno value
539 to return to the client.
543 int (*flush) (struct nbdkit_next_ops *next_ops, void *nxdata,
544 void *handle, uint32_t flags, int *err);
546 This intercepts the plugin C<.flush> method and can be used to modify
549 This function will not be called if C<.can_flush> returned false; in
550 turn, the filter should not call C<next_ops-E<gt>flush> if
551 C<next_ops-E<gt>can_flush> did not return true.
553 The parameter C<flags> exists in case of future NBD protocol
554 extensions; at this time, it will be 0 on input, and the filter should
555 not pass any flags to C<next_ops-E<gt>flush>.
557 If there is an error, C<.flush> should call C<nbdkit_error> with an
558 error message B<and> return -1 with C<err> set to the positive errno
559 value to return to the client.
563 int (*trim) (struct nbdkit_next_ops *next_ops, void *nxdata,
564 void *handle, uint32_t count, uint64_t offset,
565 uint32_t flags, int *err);
567 This intercepts the plugin C<.trim> method and can be used to modify
570 This function will not be called if C<.can_trim> returned false; in
571 turn, the filter should not call C<next_ops-E<gt>trim> if
572 C<next_ops-E<gt>can_trim> did not return true.
574 The parameter C<flags> may include C<NBDKIT_FLAG_FUA> on input based
575 on the result of C<.can_fua>. In turn, the filter should only pass
576 C<NBDKIT_FLAG_FUA> on to C<next_ops-E<gt>trim> if
577 C<next_ops-E<gt>can_fua> returned a positive value.
579 If there is an error, C<.trim> should call C<nbdkit_error> with an
580 error message B<and> return -1 with C<err> set to the positive errno
581 value to return to the client.
585 int (*zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
586 void *handle, uint32_t count, uint64_t offset, uint32_t flags,
589 This intercepts the plugin C<.zero> method and can be used to modify
592 This function will not be called if C<.can_zero> returned
593 C<NBDKIT_ZERO_NONE>; in turn, the filter should not call
594 C<next_ops-E<gt>zero> if C<next_ops-E<gt>can_zero> returned
597 On input, the parameter C<flags> may include C<NBDKIT_FLAG_MAY_TRIM>
598 unconditionally, C<NBDKIT_FLAG_FUA> based on the result of
599 C<.can_fua>, and C<NBDKIT_FLAG_FAST_ZERO> based on the result of
600 C<.can_fast_zero>. In turn, the filter may pass
601 C<NBDKIT_FLAG_MAY_TRIM> unconditionally, but should only pass
602 C<NBDKIT_FLAG_FUA> or C<NBDKIT_FLAG_FAST_ZERO> on to
603 C<next_ops-E<gt>zero> if the corresponding C<next_ops-E<gt>can_fua> or
604 C<next_ops-E<gt>can_fast_zero> returned a positive value.
606 Note that unlike the plugin C<.zero> which is permitted to fail with
607 C<ENOTSUP> or C<EOPNOTSUPP> to force a fallback to C<.pwrite>, the
608 function C<next_ops-E<gt>zero> will not fail with C<err> set to
609 C<ENOTSUP> or C<EOPNOTSUPP> unless C<NBDKIT_FLAG_FAST_ZERO> was used,
610 because otherwise the fallback has already taken place.
612 If there is an error, C<.zero> should call C<nbdkit_error> with an
613 error message B<and> return -1 with C<err> set to the positive errno
614 value to return to the client. The filter should not fail with
615 C<ENOTSUP> or C<EOPNOTSUPP> unless C<flags> includes
616 C<NBDKIT_FLAG_FAST_ZERO> (while plugins have automatic fallback to
617 C<.pwrite>, filters do not).
621 int (*extents) (struct nbdkit_next_ops *next_ops, void *nxdata,
622 void *handle, uint32_t count, uint64_t offset, uint32_t flags,
623 struct nbdkit_extents *extents,
626 This intercepts the plugin C<.extents> method and can be used to
627 modify extent requests.
629 This function will not be called if C<.can_extents> returned false; in
630 turn, the filter should not call C<next_ops-E<gt>extents> if
631 C<next_ops-E<gt>can_extents> did not return true.
633 It is possible for filters to transform the extents list received back
634 from the layer below. Without error checking it would look like this:
636 myfilter_extents (..., uint32_t count, uint64_t offset, ...)
639 struct nbdkit_extents *extents2;
640 struct nbdkit_extent e;
643 size = next_ops->get_size (nxdata);
644 extents2 = nbdkit_extents_new (offset + shift, size);
645 next_ops->extents (nxdata, count, offset + shift, flags, extents2, err);
646 for (i = 0; i < nbdkit_extents_count (extents2); ++i) {
647 e = nbdkit_get_extent (extents2, i);
649 nbdkit_add_extent (extents, e.offset, e.length, e.type);
651 nbdkit_extents_free (extents2);
654 If there is an error, C<.extents> should call C<nbdkit_error> with an
655 error message B<and> return -1 with C<err> set to the positive errno
656 value to return to the client.
658 =head3 Allocating and freeing nbdkit_extents list
660 Two functions are provided to filters only for allocating and freeing
663 struct nbdkit_extents *nbdkit_extents_new (uint64_t start, uint64_t end);
665 Allocates and returns a new, empty extents list. The C<start>
666 parameter is the start of the range described in the list, and the
667 C<end> parameter is the offset of the byte beyond the end. Normally
668 you would pass in C<offset> as the start and the size of the plugin as
669 the end, but for filters which adjust offsets, they should pass in the
672 On error this function can return C<NULL>. In this case it calls
673 C<nbdkit_error> and/or C<nbdkit_set_error> as required. C<errno> will
674 be set to a suitable value.
676 void nbdkit_extents_free (struct nbdkit_extents *);
678 Frees an existing extents list.
680 =head3 Iterating over nbdkit_extents list
682 Two functions are provided to filters only to iterate over the extents
685 size_t nbdkit_extents_count (const struct nbdkit_extents *);
687 Returns the number of extents in the list.
689 struct nbdkit_extent {
694 struct nbdkit_extent nbdkit_get_extent (const struct nbdkit_extents *,
697 Returns a copy of the C<i>'th extent.
701 int (*cache) (struct nbdkit_next_ops *next_ops, void *nxdata,
702 void *handle, uint32_t count, uint64_t offset,
703 uint32_t flags, int *err);
705 This intercepts the plugin C<.cache> method and can be used to modify
708 This function will not be called if C<.can_cache> returned
709 C<NBDKIT_CACHE_NONE> or C<NBDKIT_CACHE_EMULATE>; in turn, the filter
710 should not call C<next_ops-E<gt>cache> unless
711 C<next_ops-E<gt>can_cache> returned C<NBDKIT_CACHE_NATIVE>.
713 The parameter C<flags> exists in case of future NBD protocol
714 extensions; at this time, it will be 0 on input, and the filter should
715 not pass any flags to C<next_ops-E<gt>cache>.
717 If there is an error, C<.cache> should call C<nbdkit_error> with an
718 error message B<and> return -1 with C<err> set to the positive errno
719 value to return to the client.
721 =head1 ERROR HANDLING
723 If there is an error in the filter itself, the filter should call
724 C<nbdkit_error> to report an error message. If the callback is
725 involved in serving data, the explicit C<err> parameter determines the
726 error code that will be sent to the client; other callbacks should
727 return the appropriate error indication, eg. C<NULL> or C<-1>.
729 C<nbdkit_error> has the following prototype and works like
732 void nbdkit_error (const char *fs, ...);
733 void nbdkit_verror (const char *fs, va_list args);
735 For convenience, C<nbdkit_error> preserves the value of C<errno>, and
736 also supports the glibc extension of a single C<%m> in a format string
737 expanding to C<strerror(errno)>, even on platforms that don't support
742 Run the server with I<-f> and I<-v> options so it doesn't fork and you
743 can see debugging information:
745 nbdkit -fv --filter=./myfilter.so plugin [key=value [key=value [...]]]
747 To print debugging information from within the filter, call
748 C<nbdkit_debug>, which has the following prototype and works like
751 void nbdkit_debug (const char *fs, ...);
752 void nbdkit_vdebug (const char *fs, va_list args);
754 For convenience, C<nbdkit_debug> preserves the value of C<errno>, and
755 also supports the glibc extension of a single C<%m> in a format string
756 expanding to C<strerror(errno)>, even on platforms that don't support
757 that natively. Note that C<nbdkit_debug> only prints things when the
758 server is in verbose mode (I<-v> option).
762 Debug Flags in filters work exactly the same way as plugins. See
763 L<nbdkit-plugin(3)/Debug Flags>.
765 =head1 INSTALLING THE FILTER
767 The filter is a C<*.so> file and possibly a manual page. You can of
768 course install the filter C<*.so> file wherever you want, and users
769 will be able to use it by running:
771 nbdkit --filter=/path/to/filter.so plugin [args]
773 However B<if> the shared library has a name of the form
774 C<nbdkit-I<name>-filter.so> B<and if> the library is installed in the
775 C<$filterdir> directory, then users can be run it by only typing:
777 nbdkit --filter=name plugin [args]
779 The location of the C<$filterdir> directory is set when nbdkit is
780 compiled and can be found by doing:
784 If using the pkg-config/pkgconf system then you can also find the
785 filter directory at compile time by doing:
787 pkgconf nbdkit --variable=filterdir
789 =head1 PKG-CONFIG/PKGCONF
791 nbdkit provides a pkg-config/pkgconf file called C<nbdkit.pc> which
792 should be installed on the correct path when the nbdkit development
793 environment is installed. You can use this in autoconf
794 F<configure.ac> scripts to test for the development environment:
796 PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])
798 The above will fail unless nbdkit E<ge> 1.2.3 and the header file is
799 installed, and will set C<NBDKIT_CFLAGS> and C<NBDKIT_LIBS>
800 appropriately for compiling filters.
802 You can also run pkg-config/pkgconf directly, for example:
804 if ! pkgconf nbdkit --exists; then
805 echo "you must install the nbdkit development environment"
809 You can also substitute the filterdir variable by doing:
811 PKG_CHECK_VAR([NBDKIT_FILTERDIR], [nbdkit], [filterdir])
813 which defines C<$(NBDKIT_FILTERDIR)> in automake-generated Makefiles.
820 Standard filters provided by nbdkit:
832 Copyright (C) 2013-2020 Red Hat Inc.