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 some function types ("nbdkit_next_config",
127 "nbdkit_next_config_complete", "nbdkit_next_get_ready",
128 "nbdkit_next_preconnect", "nbdkit_next_open") and a structure called
129 "struct nbdkit_next_ops". These abstract the next plugin or filter in
130 the chain. There is also an opaque pointer "nxdata" which must be
131 passed along when calling these functions. The value of "nxdata"
132 passed to ".open" has a stable lifetime that lasts to the corresponding
133 ".close", with all intermediate functions (such as ".pread") receiving
134 the same value for convenience; the only exceptions where "nxdata" is
135 not reused are ".config", ".config_complete", ".get_ready", and
136 ".preconnect", which are called outside the lifetime of a connection.
137 Next config, open and close
139 The filter’s ".config", ".config_complete", ".get_ready" and ".open"
140 methods may only call the next ".config", ".config_complete",
141 ".get_ready" and ".open" method in the chain (optionally for
142 ".config").
143 The filter’s ".close" method is called when an old connection closed,
145 and this has no "next" parameter because it cannot be short-circuited.
146 "next_ops"
148 The filter’s other methods like ".prepare", ".get_size", ".pread" etc ―
149 always called in the context of a connection ― are passed a pointer to
150 "struct nbdkit_next_ops" which contains a comparable set of accessors
151 to plugin methods that can be called during a connection. The
152 "next_ops" parameter is stable between ".prepare" and ".finalize";
153 intermediate functions (such as ".pread") receive the same value for
154 convenience.
155 It is possible for a filter to issue (for example) extra
157 "next_ops->pread" calls in response to a single ".pwrite" call.
158 Note that the semantics of the functions in "struct nbdkit_next_ops"
160 are slightly different from what a plugin implements: for example, when
161 a plugin's ".pread" returns -1 on error, the error value to advertise
162 to the client is implicit (via the plugin calling "nbdkit_set_error" or
163 setting "errno"), whereas "next_ops->pread" exposes this via an
164 explicit parameter, allowing a filter to learn or modify this error if
165 desired.
166 There is also a "next_ops->reopen" function which is used by
168 nbdkit-retry-filter(3) to close and reopen the underlying plugin. It
169 should be used with caution because it is difficult to use safely.
170 Other considerations
172 You can modify parameters when you call the "next" function. However
173 be careful when modifying strings because for some methods (eg.
174 ".config") the plugin may save the string pointer that you pass along.
175 So you may have to ensure that the string is not freed for the lifetime
176 of the server.
177 Note that if your filter registers a callback but in that callback it
179 doesn't call the "next" function then the corresponding method in the
180 plugin will never be called. In particular, your ".open" method, if
181 you have one, must call the ".next" method.
182
184 "struct nbdkit_filter" has some static fields describing the filter and
185 optional callback functions which can be used to intercept plugin
186 methods.
187 ".name"
189 const char *name;
190 This field (a string) is required, and must contain only ASCII
192 alphanumeric characters and be unique amongst all filters.
193 ".longname"
195 const char *longname;
196 An optional free text name of the filter. This field is used in error
198 messages.
199 ".description"
201 const char *description;
202 An optional multi-line description of the filter.
204 ".load"
206 void load (void);
207 This is called once just after the filter is loaded into memory. You
209 can use this to perform any global initialization needed by the filter.
210 ".unload"
212 void unload (void);
213 This may be called once just before the filter is unloaded from memory.
215 Note that it's not guaranteed that ".unload" will always be called (eg.
216 the server might be killed or segfault), so you should try to make the
217 filter as robust as possible by not requiring cleanup. See also
218 "SHUTDOWN" in nbdkit-plugin(3).
219 ".config"
221 int (*config) (nbdkit_next_config *next, void *nxdata,
222 const char *key, const char *value);
223 This intercepts the plugin ".config" method and can be used by the
225 filter to parse its own command line parameters. You should try to
226 make sure that command line parameter keys that the filter uses do not
227 conflict with ones that could be used by a plugin.
228 If there is an error, ".config" should call "nbdkit_error" with an
230 error message and return "-1".
231 ".config_complete"
233 int (*config_complete) (nbdkit_next_config_complete *next, void *nxdata);
234 This intercepts the plugin ".config_complete" method and can be used to
236 ensure that all parameters needed by the filter were supplied on the
237 command line.
238 If there is an error, ".config_complete" should call "nbdkit_error"
240 with an error message and return "-1".
241 ".config_help"
243 const char *config_help;
244 This optional multi-line help message should summarize any "key=value"
246 parameters that it takes. It does not need to repeat what already
247 appears in ".description".
248 If the filter doesn't take any config parameters you should probably
250 omit this.
251 ".thread_model"
253 int (*thread_model) (void);
254 Filters may tighten (but not relax) the thread model of the plugin, by
256 defining this callback. Note that while plugins use a compile-time
257 definition of "THREAD_MODEL", filters do not need to declare a model at
258 compile time; instead, this callback is called after ".config_complete"
259 and before any connections are created. See "THREADS" in
260 nbdkit-plugin(3) for a discussion of thread models.
261 The final thread model used by nbdkit is the smallest (ie. most
263 serialized) out of all the filters and the plugin, and applies for all
264 connections. Requests for a model larger than permitted by the plugin
265 are silently ignored. It is acceptable for decisions made during
266 ".config" and ".config_complete" to determine which model to request.
267 This callback is optional; if it is not present, the filter must be
269 written to handle fully parallel requests, including when multiple
270 requests are issued in parallel on the same connection, similar to a
271 plugin requesting "NBDKIT_THREAD_MODEL_PARALLEL". This ensures the
272 filter doesn't slow down other filters or plugins.
273 If there is an error, ".thread_model" should call "nbdkit_error" with
275 an error message and return "-1".
276 ".get_ready"
278 int (*get_ready) (nbdkit_next_get_ready *next, void *nxdata);
279 This intercepts the plugin ".get_ready" method and can be used by the
281 filter to get ready to serve requests.
282 If there is an error, ".get_ready" should call "nbdkit_error" with an
284 error message and return "-1".
285 ".preconnect"
287 int (*preconnect) (nbdkit_next_preconnect *next, void *nxdata,
288 int readonly);
289 This intercepts the plugin ".preconnect" method and can be used to
291 filter access to the server.
292 If there is an error, ".preconnect" should call "nbdkit_error" with an
294 error message and return "-1".
295 ".open"
297 void * (*open) (nbdkit_next_open *next, void *nxdata,
298 int readonly);
299 This is called when a new client connection is opened and can be used
301 to allocate any per-connection data structures needed by the filter.
302 The handle (which is not the same as the plugin handle) is passed back
303 to other filter callbacks and could be freed in the ".close" callback.
304 Note that the handle is completely opaque to nbdkit, but it must not be
306 NULL. If you don't need to use a handle, return
307 "NBDKIT_HANDLE_NOT_NEEDED" which is a static non-NULL pointer.
308 If there is an error, ".open" should call "nbdkit_error" with an error
310 message and return "NULL".
311 This callback is optional, but if provided, it must call "next",
313 passing a value for "readonly" according to how the filter plans to use
314 the plugin. Typically, the filter passes the same value as it
315 received, or passes true to provide a writable layer on top of a read-
316 only backend. However, it is also acceptable to attempt write access
317 to the plugin even if this filter is readonly, such as when a file
318 system mounted read-only still requires write access to the underlying
319 device in case a journal needs to be replayed for consistency as part
320 of the mounting process. The filter should generally call "next" as
321 its first step, to allocate from the plugin outwards, so that ".close"
322 running from the outer filter to the plugin will be in reverse.
323 ".close"
325 void (*close) (void *handle);
326 This is called when the client closes the connection. It should clean
328 up any per-connection resources used by the filter. It is called
329 beginning with the outermost filter and ending with the plugin (the
330 opposite order of ".open" if all filters call "next" first), although
331 this order technically does not matter since the callback cannot report
332 failures or access the underlying plugin.
333 ".prepare"
335 ".finalize"
336 int (*prepare) (struct nbdkit_next_ops *next_ops, void *nxdata,
337 void *handle, int readonly);
338 int (*finalize) (struct nbdkit_next_ops *next_ops, void *nxdata,
339 void *handle);
340 These two methods can be used to perform any necessary operations just
342 after opening the connection (".prepare") or just before closing the
343 connection (".finalize").
344 For example if you need to scan the underlying disk to check for a
346 partition table, you could do it in your ".prepare" method (calling the
347 plugin's ".pread" method via "next_ops"). Or if you need to cleanly
348 update superblock data in the image on close you can do it in your
349 ".finalize" method (calling the plugin's ".pwrite" method). Doing
350 these things in the filter's ".open" or ".close" method is not
351 possible.
352 For ".prepare", the value of "readonly" is the same as was passed to
354 ".open", declaring how this filter will be used.
355 There is no "next_ops->prepare" or "next_ops->finalize". Unlike other
357 filter methods, prepare and finalize are not chained through the
358 "next_ops" structure. Instead the core nbdkit server calls the prepare
359 and finalize methods of all filters. Prepare methods are called
360 starting with the filter closest to the plugin and proceeding outwards
361 (matching the order of ".open" if all filters call "next" before doing
362 anything locally). Finalize methods are called in the reverse order of
363 prepare methods, with the outermost filter first (and matching the
364 order of ".close"), and only if the prepare method succeeded.
365 If there is an error, both callbacks should call "nbdkit_error" with an
367 error message and return "-1". An error in ".prepare" is reported to
368 the client, but leaves the connection open (a client may try again with
369 a different export name, for example); while an error in ".finalize"
370 forces the client to disconnect.
371 ".get_size"
373 int64_t (*get_size) (struct nbdkit_next_ops *next_ops, void *nxdata,
374 void *handle);
375 This intercepts the plugin ".get_size" method and can be used to read
377 or modify the apparent size of the block device that the NBD client
378 will see.
379 The returned size must be ≥ 0. If there is an error, ".get_size"
381 should call "nbdkit_error" with an error message and return "-1". This
382 function is only called once per connection and cached by nbdkit.
383 Similarly, repeated calls to "next_ops->get_size" will return a cached
384 value.
385 ".can_write"
387 ".can_flush"
388 ".is_rotational"
389 ".can_trim"
390 ".can_zero"
391 ".can_fast_zero"
392 ".can_extents"
393 ".can_fua"
394 ".can_multi_conn"
395 ".can_cache"
396 int (*can_write) (struct nbdkit_next_ops *next_ops, void *nxdata,
397 void *handle);
398 int (*can_flush) (struct nbdkit_next_ops *next_ops, void *nxdata,
399 void *handle);
400 int (*is_rotational) (struct nbdkit_next_ops *next_ops,
401 void *nxdata,
402 void *handle);
403 int (*can_trim) (struct nbdkit_next_ops *next_ops, void *nxdata,
404 void *handle);
405 int (*can_zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
406 void *handle);
407 int (*can_fast_zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
408 void *handle);
409 int (*can_extents) (struct nbdkit_next_ops *next_ops, void *nxdata,
410 void *handle);
411 int (*can_fua) (struct nbdkit_next_ops *next_ops, void *nxdata,
412 void *handle);
413 int (*can_multi_conn) (struct nbdkit_next_ops *next_ops, void *nxdata,
414 void *handle);
415 int (*can_cache) (struct nbdkit_next_ops *next_ops, void *nxdata,
416 void *handle);
417 These intercept the corresponding plugin methods, and control feature
419 bits advertised to the client.
420 Of note, the semantics of ".can_zero" callback in the filter are
422 slightly different from the plugin, and must be one of three success
423 values visible only to filters:
424 "NBDKIT_ZERO_NONE"
426 Completely suppress advertisement of write zero support (this can
427 only be done from filters, not plugins).
428 "NBDKIT_ZERO_EMULATE"
430 Inform nbdkit that write zeroes should immediately fall back to
431 ".pwrite" emulation without trying ".zero" (this value is returned
432 by "next_ops->can_zero" if the plugin returned false in its
433 ".can_zero").
434 "NBDKIT_ZERO_NATIVE"
436 Inform nbdkit that write zeroes should attempt to use ".zero",
437 although it may still fall back to ".pwrite" emulation for
438 "ENOTSUP" or "EOPNOTSUPP" failures (this value is returned by
439 "next_ops->can_zero" if the plugin returned true in its
440 ".can_zero").
441 Remember that most of the feature check functions return merely a
443 boolean success value, while ".can_zero", ".can_fua" and ".can_cache"
444 have three success values.
445 The difference between ".can_fua" values may affect choices made in the
447 filter: when splitting a write request that requested FUA from the
448 client, if "next_ops->can_fua" returns "NBDKIT_FUA_NATIVE", then the
449 filter should pass the FUA flag on to each sub-request; while if it is
450 known that FUA is emulated by a flush because of a return of
451 "NBDKIT_FUA_EMULATE", it is more efficient to only flush once after all
452 sub-requests have completed (often by passing "NBDKIT_FLAG_FUA" on to
453 only the final sub-request, or by dropping the flag and ending with a
454 direct call to "next_ops->flush").
455 If there is an error, the callback should call "nbdkit_error" with an
457 error message and return "-1". These functions are called at most once
458 per connection and cached by nbdkit. Similarly, repeated calls to any
459 of the "next_ops" counterparts will return a cached value; by calling
460 into the plugin during ".prepare", you can ensure that later use of the
461 cached values during data commands like <.pwrite> will not fail.
462 ".pread"
464 int (*pread) (struct nbdkit_next_ops *next_ops, void *nxdata,
465 void *handle, void *buf, uint32_t count, uint64_t offset,
466 uint32_t flags, int *err);
467 This intercepts the plugin ".pread" method and can be used to read or
469 modify data read by the plugin.
470 The parameter "flags" exists in case of future NBD protocol extensions;
472 at this time, it will be 0 on input, and the filter should not pass any
473 flags to "next_ops->pread".
474 If there is an error (including a short read which couldn't be
476 recovered from), ".pread" should call "nbdkit_error" with an error
477 message and return -1 with "err" set to the positive errno value to
478 return to the client.
479 ".pwrite"
481 int (*pwrite) (struct nbdkit_next_ops *next_ops, void *nxdata,
482 void *handle,
483 const void *buf, uint32_t count, uint64_t offset,
484 uint32_t flags, int *err);
485 This intercepts the plugin ".pwrite" method and can be used to modify
487 data written by the plugin.
488 This function will not be called if ".can_write" returned false; in
490 turn, the filter should not call "next_ops->pwrite" if
491 "next_ops->can_write" did not return true.
492 The parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on
494 the result of ".can_fua". In turn, the filter should only pass
495 "NBDKIT_FLAG_FUA" on to "next_ops->pwrite" if "next_ops->can_fua"
496 returned a positive value.
497 If there is an error (including a short write which couldn't be
499 recovered from), ".pwrite" should call "nbdkit_error" with an error
500 message and return -1 with "err" set to the positive errno value to
501 return to the client.
502 ".flush"
504 int (*flush) (struct nbdkit_next_ops *next_ops, void *nxdata,
505 void *handle, uint32_t flags, int *err);
506 This intercepts the plugin ".flush" method and can be used to modify
508 flush requests.
509 This function will not be called if ".can_flush" returned false; in
511 turn, the filter should not call "next_ops->flush" if
512 "next_ops->can_flush" did not return true.
513 The parameter "flags" exists in case of future NBD protocol extensions;
515 at this time, it will be 0 on input, and the filter should not pass any
516 flags to "next_ops->flush".
517 If there is an error, ".flush" should call "nbdkit_error" with an error
519 message and return -1 with "err" set to the positive errno value to
520 return to the client.
521 ".trim"
523 int (*trim) (struct nbdkit_next_ops *next_ops, void *nxdata,
524 void *handle, uint32_t count, uint64_t offset,
525 uint32_t flags, int *err);
526 This intercepts the plugin ".trim" method and can be used to modify
528 trim requests.
529 This function will not be called if ".can_trim" returned false; in
531 turn, the filter should not call "next_ops->trim" if
532 "next_ops->can_trim" did not return true.
533 The parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on
535 the result of ".can_fua". In turn, the filter should only pass
536 "NBDKIT_FLAG_FUA" on to "next_ops->trim" if "next_ops->can_fua"
537 returned a positive value.
538 If there is an error, ".trim" should call "nbdkit_error" with an error
540 message and return -1 with "err" set to the positive errno value to
541 return to the client.
542 ".zero"
544 int (*zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
545 void *handle, uint32_t count, uint64_t offset, uint32_t flags,
546 int *err);
547 This intercepts the plugin ".zero" method and can be used to modify
549 zero requests.
550 This function will not be called if ".can_zero" returned
552 "NBDKIT_ZERO_NONE"; in turn, the filter should not call
553 "next_ops->zero" if "next_ops->can_zero" returned "NBDKIT_ZERO_NONE".
554 On input, the parameter "flags" may include "NBDKIT_FLAG_MAY_TRIM"
556 unconditionally, "NBDKIT_FLAG_FUA" based on the result of ".can_fua",
557 and "NBDKIT_FLAG_FAST_ZERO" based on the result of ".can_fast_zero".
558 In turn, the filter may pass "NBDKIT_FLAG_MAY_TRIM" unconditionally,
559 but should only pass "NBDKIT_FLAG_FUA" or "NBDKIT_FLAG_FAST_ZERO" on to
560 "next_ops->zero" if the corresponding "next_ops->can_fua" or
561 "next_ops->can_fast_zero" returned a positive value.
562 Note that unlike the plugin ".zero" which is permitted to fail with
564 "ENOTSUP" or "EOPNOTSUPP" to force a fallback to ".pwrite", the
565 function "next_ops->zero" will not fail with "err" set to "ENOTSUP" or
566 "EOPNOTSUPP" unless "NBDKIT_FLAG_FAST_ZERO" was used, because otherwise
567 the fallback has already taken place.
568 If there is an error, ".zero" should call "nbdkit_error" with an error
570 message and return -1 with "err" set to the positive errno value to
571 return to the client. The filter should not fail with "ENOTSUP" or
572 "EOPNOTSUPP" unless "flags" includes "NBDKIT_FLAG_FAST_ZERO" (while
573 plugins have automatic fallback to ".pwrite", filters do not).
574 ".extents"
576 int (*extents) (struct nbdkit_next_ops *next_ops, void *nxdata,
577 void *handle, uint32_t count, uint64_t offset, uint32_t flags,
578 struct nbdkit_extents *extents,
579 int *err);
580 This intercepts the plugin ".extents" method and can be used to modify
582 extent requests.
583 This function will not be called if ".can_extents" returned false; in
585 turn, the filter should not call "next_ops->extents" if
586 "next_ops->can_extents" did not return true.
587 It is possible for filters to transform the extents list received back
589 from the layer below. Without error checking it would look like this:
590 myfilter_extents (..., uint32_t count, uint64_t offset, ...)
592 {
593 size_t i;
594 struct nbdkit_extents *extents2;
595 struct nbdkit_extent e;
596 int64_t size;
597 size = next_ops->get_size (nxdata);
599 extents2 = nbdkit_extents_new (offset + shift, size);
600 next_ops->extents (nxdata, count, offset + shift, flags, extents2, err);
601 for (i = 0; i < nbdkit_extents_count (extents2); ++i) {
602 e = nbdkit_get_extent (extents2, i);
603 e.offset -= shift;
604 nbdkit_add_extent (extents, e.offset, e.length, e.type);
605 }
606 nbdkit_extents_free (extents2);
607 }
608 If there is an error, ".extents" should call "nbdkit_error" with an
610 error message and return -1 with "err" set to the positive errno value
611 to return to the client.
612 Allocating and freeing nbdkit_extents list
614 Two functions are provided to filters only for allocating and freeing
616 the map:
617 struct nbdkit_extents *nbdkit_extents_new (uint64_t start, uint64_t end);
619 Allocates and returns a new, empty extents list. The "start" parameter
621 is the start of the range described in the list, and the "end"
622 parameter is the offset of the byte beyond the end. Normally you would
623 pass in "offset" as the start and the size of the plugin as the end,
624 but for filters which adjust offsets, they should pass in the adjusted
625 offset.
626 On error this function can return "NULL". In this case it calls
628 "nbdkit_error" and/or "nbdkit_set_error" as required. "errno" will be
629 set to a suitable value.
630 void nbdkit_extents_free (struct nbdkit_extents *);
632 Frees an existing extents list.
634 Iterating over nbdkit_extents list
636 Two functions are provided to filters only to iterate over the extents
638 in order:
639 size_t nbdkit_extents_count (const struct nbdkit_extents *);
641 Returns the number of extents in the list.
643 struct nbdkit_extent {
645 uint64_t offset;
646 uint64_t length;
647 uint32_t type;
648 };
649 struct nbdkit_extent nbdkit_get_extent (const struct nbdkit_extents *,
650 size_t i);
651 Returns a copy of the "i"'th extent.
653 ".cache"
655 int (*cache) (struct nbdkit_next_ops *next_ops, void *nxdata,
656 void *handle, uint32_t count, uint64_t offset,
657 uint32_t flags, int *err);
658 This intercepts the plugin ".cache" method and can be used to modify
660 cache requests.
661 This function will not be called if ".can_cache" returned
663 "NBDKIT_CACHE_NONE" or "NBDKIT_CACHE_EMULATE"; in turn, the filter
664 should not call "next_ops->cache" unless "next_ops->can_cache" returned
665 "NBDKIT_CACHE_NATIVE".
666 The parameter "flags" exists in case of future NBD protocol extensions;
668 at this time, it will be 0 on input, and the filter should not pass any
669 flags to "next_ops->cache".
670 If there is an error, ".cache" should call "nbdkit_error" with an error
672 message and return -1 with "err" set to the positive errno value to
673 return to the client.
674
676 If there is an error in the filter itself, the filter should call
677 "nbdkit_error" to report an error message. If the callback is involved
678 in serving data, the explicit "err" parameter determines the error code
679 that will be sent to the client; other callbacks should return the
680 appropriate error indication, eg. "NULL" or "-1".
681 "nbdkit_error" has the following prototype and works like printf(3):
683 void nbdkit_error (const char *fs, ...);
685 void nbdkit_verror (const char *fs, va_list args);
686 For convenience, "nbdkit_error" preserves the value of "errno", and
688 also supports the glibc extension of a single %m in a format string
689 expanding to "strerror(errno)", even on platforms that don't support
690 that natively.
691
693 Run the server with -f and -v options so it doesn't fork and you can
694 see debugging information:
695 nbdkit -fv --filter=./myfilter.so plugin [key=value [key=value [...]]]
697 To print debugging information from within the filter, call
699 "nbdkit_debug", which has the following prototype and works like
700 printf(3):
701 void nbdkit_debug (const char *fs, ...);
703 void nbdkit_vdebug (const char *fs, va_list args);
704 For convenience, "nbdkit_debug" preserves the value of "errno", and
706 also supports the glibc extension of a single %m in a format string
707 expanding to "strerror(errno)", even on platforms that don't support
708 that natively. Note that "nbdkit_debug" only prints things when the
709 server is in verbose mode (-v option).
710 Debug Flags
712 Debug Flags in filters work exactly the same way as plugins. See
713 "Debug Flags" in nbdkit-plugin(3).
714
716 The filter is a "*.so" file and possibly a manual page. You can of
717 course install the filter "*.so" file wherever you want, and users will
718 be able to use it by running:
719 nbdkit --filter=/path/to/filter.so plugin [args]
721 However if the shared library has a name of the form
723 "nbdkit-name-filter.so" and if the library is installed in the
724 $filterdir directory, then users can be run it by only typing:
725 nbdkit --filter=name plugin [args]
727 The location of the $filterdir directory is set when nbdkit is compiled
729 and can be found by doing:
730 nbdkit --dump-config
732 If using the pkg-config/pkgconf system then you can also find the
734 filter directory at compile time by doing:
735 pkg-config nbdkit --variable=filterdir
737
739 nbdkit provides a pkg-config/pkgconf file called "nbdkit.pc" which
740 should be installed on the correct path when the nbdkit development
741 environment is installed. You can use this in autoconf configure.ac
742 scripts to test for the development environment:
743 PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])
745 The above will fail unless nbdkit ≥ 1.2.3 and the header file is
747 installed, and will set "NBDKIT_CFLAGS" and "NBDKIT_LIBS" appropriately
748 for compiling filters.
749 You can also run pkg-config/pkgconf directly, for example:
751 if ! pkg-config nbdkit --exists; then
753 echo "you must install the nbdkit development environment"
754 exit 1
755 fi
756 You can also substitute the filterdir variable by doing:
758 PKG_CHECK_VAR([NBDKIT_FILTERDIR], [nbdkit], [filterdir])
760 which defines "$(NBDKIT_FILTERDIR)" in automake-generated Makefiles.
762
764 nbdkit(1), nbdkit-plugin(3).
765 Standard filters provided by nbdkit:
767 nbdkit-blocksize-filter(1), nbdkit-cache-filter(1),
769 nbdkit-cacheextents-filter(1), nbdkit-cow-filter(1),
770 nbdkit-delay-filter(1), nbdkit-error-filter(1), nbdkit-ext2-filter(1),
771 nbdkit-extentlist-filter(1), nbdkit-fua-filter(1), nbdkit-ip-filter(1),
772 nbdkit-log-filter(1), nbdkit-nocache-filter(1),
773 nbdkit-noextents-filter(1), nbdkit-nofilter-filter(1),
774 nbdkit-noparallel-filter(1), nbdkit-nozero-filter(1),
775 nbdkit-offset-filter(1), nbdkit-partition-filter(1),
776 nbdkit-rate-filter(1), nbdkit-readahead-filter(1),
777 nbdkit-retry-filter(1), nbdkit-stats-filter(1),
778 nbdkit-truncate-filter(1), nbdkit-xz-filter(1) .
779
781 Eric Blake
782 Richard W.M. Jones
784
786 Copyright (C) 2013-2019 Red Hat Inc.
787
789 Redistribution and use in source and binary forms, with or without
790 modification, are permitted provided that the following conditions are
791 met:
792 · Redistributions of source code must retain the above copyright
794 notice, this list of conditions and the following disclaimer.
795 · Redistributions in binary form must reproduce the above copyright
797 notice, this list of conditions and the following disclaimer in the
798 documentation and/or other materials provided with the
799 distribution.
800 · Neither the name of Red Hat nor the names of its contributors may
802 be used to endorse or promote products derived from this software
803 without specific prior written permission.
804 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
806 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
807 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
808 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
809 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
810 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
811 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
812 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
813 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
814 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
815 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
816nbdkit-1.18.4 2020-04-16 nbdkit-filter(3)