1nbdkit-filter(3) NBDKIT nbdkit-filter(3)
2
6 nbdkit-filter - how to write nbdkit filters
7
9 #include <nbdkit-filter.h>
10 static int
12 myfilter_config (nbdkit_next_config *next, void *nxdata,
13 const char *key, const char *value)
14 {
15 if (strcmp (key, "myparameter") == 0) {
16 // ...
17 return 0;
18 }
19 else {
20 // pass through to next filter or plugin
21 return next (nxdata, key, value);
22 }
23 }
24 static struct nbdkit_filter filter = {
26 .name = "filter",
27 .config = myfilter_config,
28 /* etc */
29 };
30 NBDKIT_REGISTER_FILTER(filter)
32 When this has been compiled to a shared library, do:
34 nbdkit [--args ...] --filter=./myfilter.so plugin [key=value ...]
36 When debugging, use the -fv options:
38 nbdkit -fv --filter=./myfilter.so plugin [key=value ...]
40
42 One or more nbdkit filters can be placed in front of an nbdkit plugin
43 to modify the behaviour of the plugin. This manual page describes how
44 to create an nbdkit filter.
45 Filters can be used for example to limit requests to an offset/limit,
47 add copy-on-write support, or inject delays or errors (for testing).
48 Different filters can be stacked:
50 NBD ┌─────────┐ ┌─────────┐ ┌────────┐
52 client ───▶│ filter1 │───▶│ filter2 │── ─ ─ ──▶│ plugin │
53 request └─────────┘ └─────────┘ └────────┘
54 Each filter intercepts plugin functions (see nbdkit-plugin(3)) and can
56 call the next filter or plugin in the chain, modifying parameters,
57 calling before the filter function, in the middle or after. Filters
58 may even short-cut the chain. As an example, to process its own
59 parameters the filter can intercept the ".config" method:
60 static int
62 myfilter_config (nbdkit_next_config *next, void *nxdata,
63 const char *key, const char *value)
64 {
65 if (strcmp (key, "myparameter") == 0) {
66 // ...
67 // here you would handle this key, value
68 // ...
69 return 0;
70 }
71 else {
72 // pass through to next filter or plugin
73 return next (nxdata, key, value);
74 }
75 }
76 static struct nbdkit_filter filter = {
78 // ...
79 .config = myfilter_config,
80 // ...
81 };
82 The call to "next (nxdata, ...)" calls the ".config" method of the next
84 filter or plugin in the chain. In the example above any instances of
85 "myparameter=..." on the command line would not be seen by the plugin.
86 To see example filters:
88 https://github.com/libguestfs/nbdkit/tree/master/filters
89 Filters must be written in C.
91 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); and
98 if we added new methods then an old filter would not see them and so
99 they would be passed unmodified through the filter, and in some cases
100 that leads to data corruption (new nbdkit cannot safely run old filters
101 unaware of new methods). Therefore, unlike plugins, you should not
102 expect to distribute filters separately from nbdkit.
103
105 All filters should start by including this header file.
106
108 All filters must define and register one "struct nbdkit_filter", which
109 contains the name of the filter and pointers to plugin methods that the
110 filter wants to intercept.
111 static struct nbdkit_filter filter = {
113 .name = "filter",
114 .longname = "My Filter",
115 .description = "This is my great filter for nbdkit",
116 .config = myfilter_config,
117 /* etc */
118 };
119 NBDKIT_REGISTER_FILTER(filter)
121 The ".name" field is the name of the filter. This is the only field
123 which is required.
124
126 nbdkit-filter.h defines three function types ("nbdkit_next_config",
127 "nbdkit_next_config_complete", "nbdkit_next_open") and a structure
128 called "struct nbdkit_next_ops". These abstract the next plugin or
129 filter in the chain. There is also an opaque pointer "nxdata" which
130 must be passed along when calling these functions.
131 Next config, open and close
133 The filter’s ".config", ".config_complete" and ".open" methods may only
134 call the next ".config", ".config_complete" and ".open" method in the
135 chain (optionally for ".config").
136 The filter’s ".close" method is called when an old connection closed,
138 and this has no "next" parameter because it cannot be short-circuited.
139 "next_ops"
141 The filter’s other methods like ".prepare", ".get_size", ".pread" etc ―
142 always called in the context of a connection ― are passed a pointer to
143 "struct nbdkit_next_ops" which contains a comparable set of accessors
144 to plugin methods that can be called during a connection.
145 It is possible for a filter to issue (for example) extra
147 "next_ops->pread" calls in response to a single ".pwrite" call.
148 Note that the semantics of the functions in "struct nbdkit_next_ops"
150 are slightly different from what a plugin implements: for example, when
151 a plugin's ".pread" returns -1 on error, the error value to advertise
152 to the client is implicit (via the plugin calling "nbdkit_set_error" or
153 setting "errno"), whereas "next_ops->pread" exposes this via an
154 explicit parameter, allowing a filter to learn or modify this error if
155 desired.
156 There is also a "next_ops->reopen" function which is used by
158 nbdkit-retry-filter(3) to close and reopen the underlying plugin. It
159 should be used with caution because it is difficult to use safely.
160 Other considerations
162 You can modify parameters when you call the "next" function. However
163 be careful when modifying strings because for some methods (eg.
164 ".config") the plugin may save the string pointer that you pass along.
165 So you may have to ensure that the string is not freed for the lifetime
166 of the server.
167 Note that if your filter registers a callback but in that callback it
169 doesn't call the "next" function then the corresponding method in the
170 plugin will never be called. In particular, your ".open" method, if
171 you have one, must call the ".next" method.
172
174 "struct nbdkit_filter" has some static fields describing the filter and
175 optional callback functions which can be used to intercept plugin
176 methods.
177 ".name"
179 const char *name;
180 This field (a string) is required, and must contain only ASCII
182 alphanumeric characters and be unique amongst all filters.
183 ".longname"
185 const char *longname;
186 An optional free text name of the filter. This field is used in error
188 messages.
189 ".description"
191 const char *description;
192 An optional multi-line description of the filter.
194 ".load"
196 void load (void);
197 This is called once just after the filter is loaded into memory. You
199 can use this to perform any global initialization needed by the filter.
200 ".unload"
202 void unload (void);
203 This may be called once just before the filter is unloaded from memory.
205 Note that it's not guaranteed that ".unload" will always be called (eg.
206 the server might be killed or segfault), so you should try to make the
207 filter as robust as possible by not requiring cleanup. See also
208 "SHUTDOWN" in nbdkit-plugin(3).
209 ".config"
211 int (*config) (nbdkit_next_config *next, void *nxdata,
212 const char *key, const char *value);
213 This intercepts the plugin ".config" method and can be used by the
215 filter to parse its own command line parameters. You should try to
216 make sure that command line parameter keys that the filter uses do not
217 conflict with ones that could be used by a plugin.
218 If there is an error, ".config" should call "nbdkit_error" with an
220 error message and return "-1".
221 ".config_complete"
223 int (*config_complete) (nbdkit_next_config_complete *next, void *nxdata);
224 This intercepts the plugin ".config_complete" method and can be used to
226 ensure that all parameters needed by the filter were supplied on the
227 command line.
228 If there is an error, ".config_complete" should call "nbdkit_error"
230 with an error message and return "-1".
231 ".config_help"
233 const char *config_help;
234 This optional multi-line help message should summarize any "key=value"
236 parameters that it takes. It does not need to repeat what already
237 appears in ".description".
238 If the filter doesn't take any config parameters you should probably
240 omit this.
241 ".thread_model"
243 int (*thread_model) (void);
244 Filters may tighten (but not relax) the thread model of the plugin, by
246 defining this callback. Note that while plugins use a compile-time
247 definition of "THREAD_MODEL", filters do not need to declare a model at
248 compile time; instead, this callback is called after ".config_complete"
249 and before any connections are created. See "THREADS" in
250 nbdkit-plugin(3) for a discussion of thread models.
251 The final thread model used by nbdkit is the smallest (ie. most
253 serialized) out of all the filters and the plugin, and applies for all
254 connections. Requests for a model larger than permitted by the plugin
255 are silently ignored. It is acceptable for decisions made during
256 ".config" and ".config_complete" to determine which model to request.
257 This callback is optional; if it is not present, the filter must be
259 written to handle fully parallel requests, including when multiple
260 requests are issued in parallel on the same connection, similar to a
261 plugin requesting "NBDKIT_THREAD_MODEL_PARALLEL". This ensures the
262 filter doesn't slow down other filters or plugins.
263 If there is an error, ".thread_model" should call "nbdkit_error" with
265 an error message and return "-1".
266 ".open"
268 void * (*open) (nbdkit_next_open *next, void *nxdata,
269 int readonly);
270 This is called when a new client connection is opened and can be used
272 to allocate any per-connection data structures needed by the filter.
273 The handle (which is not the same as the plugin handle) is passed back
274 to other filter callbacks and could be freed in the ".close" callback.
275 Note that the handle is completely opaque to nbdkit, but it must not be
277 NULL. If you don't need to use a handle, return
278 "NBDKIT_HANDLE_NOT_NEEDED" which is a static non-NULL pointer.
279 If there is an error, ".open" should call "nbdkit_error" with an error
281 message and return "NULL".
282 This callback is optional, but if provided, it must call "next",
284 passing a value for "readonly" according to how the filter plans to use
285 the plugin. Typically, the filter passes the same value as it
286 received, or passes true to provide a writable layer on top of a read-
287 only backend. However, it is also acceptable to attempt write access
288 to the plugin even if this filter is readonly, such as when a file
289 system mounted read-only still requires write access to the underlying
290 device in case a journal needs to be replayed for consistency as part
291 of the mounting process. The filter should generally call "next" as
292 its first step, to allocate from the plugin outwards, so that ".close"
293 running from the outer filter to the plugin will be in reverse.
294 ".close"
296 void (*close) (void *handle);
297 This is called when the client closes the connection. It should clean
299 up any per-connection resources used by the filter. It is called
300 beginning with the outermost filter and ending with the plugin (the
301 opposite order of ".open" if all filters call "next" first), although
302 this order technically does not matter since the callback cannot report
303 failures or access the underlying plugin.
304 ".prepare"
306 ".finalize"
307 int (*prepare) (struct nbdkit_next_ops *next_ops, void *nxdata,
308 void *handle, int readonly);
309 int (*finalize) (struct nbdkit_next_ops *next_ops, void *nxdata,
310 void *handle);
311 These two methods can be used to perform any necessary operations just
313 after opening the connection (".prepare") or just before closing the
314 connection (".finalize").
315 For example if you need to scan the underlying disk to check for a
317 partition table, you could do it in your ".prepare" method (calling the
318 plugin's ".pread" method via "next_ops"). Or if you need to cleanly
319 update superblock data in the image on close you can do it in your
320 ".finalize" method (calling the plugin's ".pwrite" method). Doing
321 these things in the filter's ".open" or ".close" method is not
322 possible.
323 For ".prepare", the value of "readonly" is the same as was passed to
325 ".open", declaring how this filter will be used.
326 There is no "next_ops->prepare" or "next_ops->finalize". Unlike other
328 filter methods, prepare and finalize are not chained through the
329 "next_ops" structure. Instead the core nbdkit server calls the prepare
330 and finalize methods of all filters. Prepare methods are called
331 starting with the filter closest to the plugin and proceeding outwards
332 (matching the order of ".open" if all filters call "next" before doing
333 anything locally). Finalize methods are called in the reverse order of
334 prepare methods, with the outermost filter first (and matching the
335 order of ".close"), and only if the prepare method succeeded.
336 If there is an error, both callbacks should call "nbdkit_error" with an
338 error message and return "-1". An error in ".prepare" is reported to
339 the client, but leaves the connection open (a client may try again with
340 a different export name, for example); while an error in ".finalize"
341 forces the client to disconnect.
342 ".get_size"
344 int64_t (*get_size) (struct nbdkit_next_ops *next_ops, void *nxdata,
345 void *handle);
346 This intercepts the plugin ".get_size" method and can be used to read
348 or modify the apparent size of the block device that the NBD client
349 will see.
350 The returned size must be ≥ 0. If there is an error, ".get_size"
352 should call "nbdkit_error" with an error message and return "-1". This
353 function is only called once per connection and cached by nbdkit.
354 Similarly, repeated calls to "next_ops->get_size" will return a cached
355 value.
356 ".can_write"
358 ".can_flush"
359 ".is_rotational"
360 ".can_trim"
361 ".can_zero"
362 ".can_fast_zero"
363 ".can_extents"
364 ".can_fua"
365 ".can_multi_conn"
366 ".can_cache"
367 int (*can_write) (struct nbdkit_next_ops *next_ops, void *nxdata,
368 void *handle);
369 int (*can_flush) (struct nbdkit_next_ops *next_ops, void *nxdata,
370 void *handle);
371 int (*is_rotational) (struct nbdkit_next_ops *next_ops,
372 void *nxdata,
373 void *handle);
374 int (*can_trim) (struct nbdkit_next_ops *next_ops, void *nxdata,
375 void *handle);
376 int (*can_zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
377 void *handle);
378 int (*can_fast_zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
379 void *handle);
380 int (*can_extents) (struct nbdkit_next_ops *next_ops, void *nxdata,
381 void *handle);
382 int (*can_fua) (struct nbdkit_next_ops *next_ops, void *nxdata,
383 void *handle);
384 int (*can_multi_conn) (struct nbdkit_next_ops *next_ops, void *nxdata,
385 void *handle);
386 int (*can_cache) (struct nbdkit_next_ops *next_ops, void *nxdata,
387 void *handle);
388 These intercept the corresponding plugin methods, and control feature
390 bits advertised to the client.
391 Of note, the semantics of ".can_zero" callback in the filter are
393 slightly different from the plugin, and must be one of three success
394 values visible only to filters:
395 "NBDKIT_ZERO_NONE"
397 Completely suppress advertisement of write zero support (this can
398 only be done from filters, not plugins).
399 "NBDKIT_ZERO_EMULATE"
401 Inform nbdkit that write zeroes should immediately fall back to
402 ".pwrite" emulation without trying ".zero" (this value is returned
403 by "next_ops->can_zero" if the plugin returned false in its
404 ".can_zero").
405 "NBDKIT_ZERO_NATIVE"
407 Inform nbdkit that write zeroes should attempt to use ".zero",
408 although it may still fall back to ".pwrite" emulation for
409 "ENOTSUP" or "EOPNOTSUPP" failures (this value is returned by
410 "next_ops->can_zero" if the plugin returned true in its
411 ".can_zero").
412 Remember that most of the feature check functions return merely a
414 boolean success value, while ".can_zero", ".can_fua" and ".can_cache"
415 have three success values.
416 The difference between ".can_fua" values may affect choices made in the
418 filter: when splitting a write request that requested FUA from the
419 client, if "next_ops->can_fua" returns "NBDKIT_FUA_NATIVE", then the
420 filter should pass the FUA flag on to each sub-request; while if it is
421 known that FUA is emulated by a flush because of a return of
422 "NBDKIT_FUA_EMULATE", it is more efficient to only flush once after all
423 sub-requests have completed (often by passing "NBDKIT_FLAG_FUA" on to
424 only the final sub-request, or by dropping the flag and ending with a
425 direct call to "next_ops->flush").
426 If there is an error, the callback should call "nbdkit_error" with an
428 error message and return "-1". These functions are called at most once
429 per connection and cached by nbdkit. Similarly, repeated calls to any
430 of the "next_ops" counterparts will return a cached value; by calling
431 into the plugin during ".prepare", you can ensure that later use of the
432 cached values during data commands like <.pwrite> will not fail.
433 ".pread"
435 int (*pread) (struct nbdkit_next_ops *next_ops, void *nxdata,
436 void *handle, void *buf, uint32_t count, uint64_t offset,
437 uint32_t flags, int *err);
438 This intercepts the plugin ".pread" method and can be used to read or
440 modify data read by the plugin.
441 The parameter "flags" exists in case of future NBD protocol extensions;
443 at this time, it will be 0 on input, and the filter should not pass any
444 flags to "next_ops->pread".
445 If there is an error (including a short read which couldn't be
447 recovered from), ".pread" should call "nbdkit_error" with an error
448 message and return -1 with "err" set to the positive errno value to
449 return to the client.
450 ".pwrite"
452 int (*pwrite) (struct nbdkit_next_ops *next_ops, void *nxdata,
453 void *handle,
454 const void *buf, uint32_t count, uint64_t offset,
455 uint32_t flags, int *err);
456 This intercepts the plugin ".pwrite" method and can be used to modify
458 data written by the plugin.
459 This function will not be called if ".can_write" returned false; in
461 turn, the filter should not call "next_ops->pwrite" if
462 "next_ops->can_write" did not return true.
463 The parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on
465 the result of ".can_fua". In turn, the filter should only pass
466 "NBDKIT_FLAG_FUA" on to "next_ops->pwrite" if "next_ops->can_fua"
467 returned a positive value.
468 If there is an error (including a short write which couldn't be
470 recovered from), ".pwrite" should call "nbdkit_error" with an error
471 message and return -1 with "err" set to the positive errno value to
472 return to the client.
473 ".flush"
475 int (*flush) (struct nbdkit_next_ops *next_ops, void *nxdata,
476 void *handle, uint32_t flags, int *err);
477 This intercepts the plugin ".flush" method and can be used to modify
479 flush requests.
480 This function will not be called if ".can_flush" returned false; in
482 turn, the filter should not call "next_ops->flush" if
483 "next_ops->can_flush" did not return true.
484 The parameter "flags" exists in case of future NBD protocol extensions;
486 at this time, it will be 0 on input, and the filter should not pass any
487 flags to "next_ops->flush".
488 If there is an error, ".flush" should call "nbdkit_error" with an error
490 message and return -1 with "err" set to the positive errno value to
491 return to the client.
492 ".trim"
494 int (*trim) (struct nbdkit_next_ops *next_ops, void *nxdata,
495 void *handle, uint32_t count, uint64_t offset,
496 uint32_t flags, int *err);
497 This intercepts the plugin ".trim" method and can be used to modify
499 trim requests.
500 This function will not be called if ".can_trim" returned false; in
502 turn, the filter should not call "next_ops->trim" if
503 "next_ops->can_trim" did not return true.
504 The parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on
506 the result of ".can_fua". In turn, the filter should only pass
507 "NBDKIT_FLAG_FUA" on to "next_ops->trim" if "next_ops->can_fua"
508 returned a positive value.
509 If there is an error, ".trim" should call "nbdkit_error" with an error
511 message and return -1 with "err" set to the positive errno value to
512 return to the client.
513 ".zero"
515 int (*zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
516 void *handle, uint32_t count, uint64_t offset, uint32_t flags,
517 int *err);
518 This intercepts the plugin ".zero" method and can be used to modify
520 zero requests.
521 This function will not be called if ".can_zero" returned
523 "NBDKIT_ZERO_NONE"; in turn, the filter should not call
524 "next_ops->zero" if "next_ops->can_zero" returned "NBDKIT_ZERO_NONE".
525 On input, the parameter "flags" may include "NBDKIT_FLAG_MAY_TRIM"
527 unconditionally, "NBDKIT_FLAG_FUA" based on the result of ".can_fua",
528 and "NBDKIT_FLAG_FAST_ZERO" based on the result of ".can_fast_zero".
529 In turn, the filter may pass "NBDKIT_FLAG_MAY_TRIM" unconditionally,
530 but should only pass "NBDKIT_FLAG_FUA" or "NBDKIT_FLAG_FAST_ZERO" on to
531 "next_ops->zero" if the corresponding "next_ops->can_fua" or
532 "next_ops->can_fast_zero" returned a positive value.
533 Note that unlike the plugin ".zero" which is permitted to fail with
535 "ENOTSUP" or "EOPNOTSUPP" to force a fallback to ".pwrite", the
536 function "next_ops->zero" will not fail with "err" set to "ENOTSUP" or
537 "EOPNOTSUPP" unless "NBDKIT_FLAG_FAST_ZERO" was used, because otherwise
538 the fallback has already taken place.
539 If there is an error, ".zero" should call "nbdkit_error" with an error
541 message and return -1 with "err" set to the positive errno value to
542 return to the client. The filter should not fail with "ENOTSUP" or
543 "EOPNOTSUPP" unless "flags" includes "NBDKIT_FLAG_FAST_ZERO" (while
544 plugins have automatic fallback to ".pwrite", filters do not).
545 ".extents"
547 int (*extents) (struct nbdkit_next_ops *next_ops, void *nxdata,
548 void *handle, uint32_t count, uint64_t offset, uint32_t flags,
549 struct nbdkit_extents *extents,
550 int *err);
551 This intercepts the plugin ".extents" method and can be used to modify
553 extent requests.
554 This function will not be called if ".can_extents" returned false; in
556 turn, the filter should not call "next_ops->extents" if
557 "next_ops->can_extents" did not return true.
558 It is possible for filters to transform the extents list received back
560 from the layer below. Without error checking it would look like this:
561 myfilter_extents (..., uint32_t count, uint64_t offset, ...)
563 {
564 size_t i;
565 struct nbdkit_extents *extents2;
566 struct nbdkit_extent e;
567 int64_t size;
568 size = next_ops->get_size (nxdata);
570 extents2 = nbdkit_extents_new (offset + shift, size);
571 next_ops->extents (nxdata, count, offset + shift, flags, extents2, err);
572 for (i = 0; i < nbdkit_extents_count (extents2); ++i) {
573 e = nbdkit_get_extent (extents2, i);
574 e.offset -= shift;
575 nbdkit_add_extent (extents, e.offset, e.length, e.type);
576 }
577 nbdkit_extents_free (extents2);
578 }
579 If there is an error, ".extents" should call "nbdkit_error" with an
581 error message and return -1 with "err" set to the positive errno value
582 to return to the client.
583 Allocating and freeing nbdkit_extents list
585 Two functions are provided to filters only for allocating and freeing
587 the map:
588 struct nbdkit_extents *nbdkit_extents_new (uint64_t start, uint64_t end);
590 Allocates and returns a new, empty extents list. The "start" parameter
592 is the start of the range described in the list, and the "end"
593 parameter is the offset of the byte beyond the end. Normally you would
594 pass in "offset" as the start and the size of the plugin as the end,
595 but for filters which adjust offsets, they should pass in the adjusted
596 offset.
597 On error this function can return "NULL". In this case it calls
599 "nbdkit_error" and/or "nbdkit_set_error" as required. "errno" will be
600 set to a suitable value.
601 void nbdkit_extents_free (struct nbdkit_extents *);
603 Frees an existing extents list.
605 Iterating over nbdkit_extents list
607 Two functions are provided to filters only to iterate over the extents
609 in order:
610 size_t nbdkit_extents_count (const struct nbdkit_extents *);
612 Returns the number of extents in the list.
614 struct nbdkit_extent {
616 uint64_t offset;
617 uint64_t length;
618 uint32_t type;
619 };
620 struct nbdkit_extent nbdkit_get_extent (const struct nbdkit_extents *,
621 size_t i);
622 Returns a copy of the "i"'th extent.
624 ".cache"
626 int (*cache) (struct nbdkit_next_ops *next_ops, void *nxdata,
627 void *handle, uint32_t count, uint64_t offset,
628 uint32_t flags, int *err);
629 This intercepts the plugin ".cache" method and can be used to modify
631 cache requests.
632 This function will not be called if ".can_cache" returned
634 "NBDKIT_CACHE_NONE" or "NBDKIT_CACHE_EMULATE"; in turn, the filter
635 should not call "next_ops->cache" unless "next_ops->can_cache" returned
636 "NBDKIT_CACHE_NATIVE".
637 The parameter "flags" exists in case of future NBD protocol extensions;
639 at this time, it will be 0 on input, and the filter should not pass any
640 flags to "next_ops->cache".
641 If there is an error, ".cache" should call "nbdkit_error" with an error
643 message and return -1 with "err" set to the positive errno value to
644 return to the client.
645
647 If there is an error in the filter itself, the filter should call
648 "nbdkit_error" to report an error message. If the callback is involved
649 in serving data, the explicit "err" parameter determines the error code
650 that will be sent to the client; other callbacks should return the
651 appropriate error indication, eg. "NULL" or "-1".
652 "nbdkit_error" has the following prototype and works like printf(3):
654 void nbdkit_error (const char *fs, ...);
656 void nbdkit_verror (const char *fs, va_list args);
657 For convenience, "nbdkit_error" preserves the value of "errno", and
659 also supports the glibc extension of a single %m in a format string
660 expanding to "strerror(errno)", even on platforms that don't support
661 that natively.
662
664 Run the server with -f and -v options so it doesn't fork and you can
665 see debugging information:
666 nbdkit -fv --filter=./myfilter.so plugin [key=value [key=value [...]]]
668 To print debugging information from within the filter, call
670 "nbdkit_debug", which has the following prototype and works like
671 printf(3):
672 void nbdkit_debug (const char *fs, ...);
674 void nbdkit_vdebug (const char *fs, va_list args);
675 For convenience, "nbdkit_debug" preserves the value of "errno", and
677 also supports the glibc extension of a single %m in a format string
678 expanding to "strerror(errno)", even on platforms that don't support
679 that natively. Note that "nbdkit_debug" only prints things when the
680 server is in verbose mode (-v option).
681 Debug Flags
683 Debug Flags in filters work exactly the same way as plugins. See
684 "Debug Flags" in nbdkit-plugin(3).
685
687 The filter is a "*.so" file and possibly a manual page. You can of
688 course install the filter "*.so" file wherever you want, and users will
689 be able to use it by running:
690 nbdkit --filter=/path/to/filter.so plugin [args]
692 However if the shared library has a name of the form
694 "nbdkit-name-filter.so" and if the library is installed in the
695 $filterdir directory, then users can be run it by only typing:
696 nbdkit --filter=name plugin [args]
698 The location of the $filterdir directory is set when nbdkit is compiled
700 and can be found by doing:
701 nbdkit --dump-config
703 If using the pkg-config/pkgconf system then you can also find the
705 filter directory at compile time by doing:
706 pkgconf nbdkit --variable=filterdir
708
710 nbdkit provides a pkg-config/pkgconf file called "nbdkit.pc" which
711 should be installed on the correct path when the nbdkit development
712 environment is installed. You can use this in autoconf configure.ac
713 scripts to test for the development environment:
714 PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])
716 The above will fail unless nbdkit ≥ 1.2.3 and the header file is
718 installed, and will set "NBDKIT_CFLAGS" and "NBDKIT_LIBS" appropriately
719 for compiling filters.
720 You can also run pkg-config/pkgconf directly, for example:
722 if ! pkgconf nbdkit --exists; then
724 echo "you must install the nbdkit development environment"
725 exit 1
726 fi
727 You can also substitute the filterdir variable by doing:
729 PKG_CHECK_VAR([NBDKIT_FILTERDIR], [nbdkit], [filterdir])
731 which defines "$(NBDKIT_FILTERDIR)" in automake-generated Makefiles.
733
735 nbdkit(1), nbdkit-plugin(3).
736 Standard filters provided by nbdkit:
738 nbdkit-blocksize-filter(1), nbdkit-cache-filter(1),
740 nbdkit-cacheextents-filter(1), nbdkit-cow-filter(1),
741 nbdkit-delay-filter(1), nbdkit-error-filter(1), nbdkit-fua-filter(1),
742 nbdkit-log-filter(1), nbdkit-nocache-filter(1),
743 nbdkit-noextents-filter(1), nbdkit-noparallel-filter(1),
744 nbdkit-nozero-filter(1), nbdkit-offset-filter(1),
745 nbdkit-partition-filter(1), nbdkit-rate-filter(1),
746 nbdkit-readahead-filter(1), nbdkit-retry-filter(1),
747 nbdkit-stats-filter(1), nbdkit-truncate-filter(1), nbdkit-xz-filter(1)
748 .
749
751 Eric Blake
752 Richard W.M. Jones
754
756 Copyright (C) 2013-2019 Red Hat Inc.
757
759 Redistribution and use in source and binary forms, with or without
760 modification, are permitted provided that the following conditions are
761 met:
762 · Redistributions of source code must retain the above copyright
764 notice, this list of conditions and the following disclaimer.
765 · Redistributions in binary form must reproduce the above copyright
767 notice, this list of conditions and the following disclaimer in the
768 documentation and/or other materials provided with the
769 distribution.
770 · Neither the name of Red Hat nor the names of its contributors may
772 be used to endorse or promote products derived from this software
773 without specific prior written permission.
774 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
776 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
777 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
778 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
779 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
780 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
781 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
782 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
783 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
784 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
785 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
786nbdkit-1.16.1 2019-12-03 nbdkit-filter(3)