Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
nbdkit-filter(3)		    NBDKIT		      nbdkit-filter(3)

NAME
       nbdkit-filter - how to write nbdkit filters

SYNOPSIS
	#include <nbdkit-filter.h>

	static int
	myfilter_config	(nbdkit_next_config *next, void	*nxdata,
			 const char *key, const	char *value)
	{
	  if (strcmp (key, "myparameter") == 0)	{
	    // ...
	    return 0;
	  }
	  else {
	    // pass through to next filter or plugin
	    return next	(nxdata, key, value);
	  }
	}

	static struct nbdkit_filter filter = {
	  .name		     = "filter",
	  .config	     = myfilter_config,
	  /* etc */
	};

	NBDKIT_REGISTER_FILTER(filter)

       When this has been compiled to a	shared library,	do:

	nbdkit [--args ...] --filter=./myfilter.so plugin [key=value ...]

       When debugging, use the -fv options:

	nbdkit -fv --filter=./myfilter.so plugin [key=value ...]

DESCRIPTION
       One or more nbdkit filters can be placed	in front of an nbdkit plugin
       to modify the behaviour of the plugin.  This manual page	describes how
       to create an nbdkit filter.

       Filters can be used for example to limit	requests to an offset/limit,
       add copy-on-write support, or inject delays or errors (for testing).

       Different filters can be	stacked:

	    NBD	    aaaaaaaaaaa	   aaaaaaaaaaa		aaaaaaaaaa
	 client	aaaa<paragraph>a filter1 aaaaa<paragraph>a filter2 aaa a a aaa<paragraph>a plugin a
	request	    aaaaaaaaaaa	   aaaaaaaaaaa		aaaaaaaaaa

       Each filter intercepts plugin functions (see nbdkit-plugin(3)) and can
       call the	next filter or plugin in the chain, modifying parameters,
       calling before the filter function, in the middle or after.  Filters
       may even	short-cut the chain.  As an example, to	process	its own
       parameters the filter can intercept the ".config" method:

	static int
	myfilter_config	(nbdkit_next_config *next, void	*nxdata,
			 const char *key, const	char *value)
	{
	  if (strcmp (key, "myparameter") == 0)	{
	    // ...
	    // here you	would handle this key, value
	    // ...
	    return 0;
	  }
	  else {
	    // pass through to next filter or plugin
	    return next	(nxdata, key, value);
	  }
	}

	static struct nbdkit_filter filter = {
	  // ...
	  .config	     = myfilter_config,
	  // ...
	};

       The call	to "next (nxdata, ...)"	calls the ".config" method of the next
       filter or plugin	in the chain.  In the example above any	instances of
       "myparameter=..." on the	command	line would not be seen by the plugin.

       To see example filters:
       https://github.com/libguestfs/nbdkit/tree/master/filters

       Filters must be written in C.

       Unlike plugins, where we	provide	a stable ABI guarantee that permits
       operation across	version	differences, filters can only be run with the
       same version of nbdkit that they	were compiled with.  The reason	for
       this is two-fold: the filter API	includes access	to struct
       nbdkit_next_ops that is likely to change	if new callbacks are added
       (old nbdkit cannot safely run new filters that access new methods); and
       if we added new methods then an old filter would	not see	them and so
       they would be passed unmodified through the filter, and in some cases
       that leads to data corruption (new nbdkit cannot	safely run old filters
       unaware of new methods).	 Therefore, unlike plugins, you	should not
       expect to distribute filters separately from nbdkit.

"#include <nbdkit-filter.h>"
       All filters should start	by including this header file.

"struct	nbdkit_filter"
       All filters must	define and register one	"struct	nbdkit_filter",	which
       contains	the name of the	filter and pointers to plugin methods that the
       filter wants to intercept.

	static struct nbdkit_filter filter = {
	  .name		     = "filter",
	  .longname	     = "My Filter",
	  .description	     = "This is	my great filter	for nbdkit",
	  .config	     = myfilter_config,
	  /* etc */
	};

	NBDKIT_REGISTER_FILTER(filter)

       The ".name" field is the	name of	the filter.  This is the only field
       which is	required.

NEXT PLUGIN
       nbdkit-filter.h defines some function types ("nbdkit_next_config",
       "nbdkit_next_config_complete", "nbdkit_next_get_ready",
       "nbdkit_next_preconnect", "nbdkit_next_open") and a structure called
       "struct nbdkit_next_ops".  These	abstract the next plugin or filter in
       the chain.  There is also an opaque pointer "nxdata" which must be
       passed along when calling these functions.  The value of	"nxdata"
       passed to ".open" has a stable lifetime that lasts to the corresponding
       ".close", with all intermediate functions (such as ".pread") receiving
       the same	value for convenience; the only	exceptions where "nxdata" is
       not reused are ".config", ".config_complete", ".get_ready", and
       ".preconnect", which are	called outside the lifetime of a connection.

   Next	config,	open and close
       The filteras ".config", ".config_complete", ".get_ready"	and ".open"
       methods may only	call the next ".config", ".config_complete",
       ".get_ready" and	".open"	method in the chain (optionally	for
       ".config").

       The filteras ".close" method is called when an old connection closed,
       and this	has no "next" parameter	because	it cannot be short-circuited.

   "next_ops"
       The filteras other methods like ".prepare", ".get_size",	".pread" etc a
       always called in	the context of a connection a are passed a pointer to
       "struct nbdkit_next_ops"	which contains a comparable set	of accessors
       to plugin methods that can be called during a connection.  The
       "next_ops" parameter is stable between ".prepare" and ".finalize";
       intermediate functions (such as ".pread") receive the same value	for
       convenience.

       It is possible for a filter to issue (for example) extra
       "next_ops->pread" calls in response to a	single ".pwrite" call.

       Note that the semantics of the functions	in "struct nbdkit_next_ops"
       are slightly different from what	a plugin implements: for example, when
       a plugin's ".pread" returns -1 on error,	the error value	to advertise
       to the client is	implicit (via the plugin calling "nbdkit_set_error" or
       setting "errno"), whereas "next_ops->pread" exposes this	via an
       explicit	parameter, allowing a filter to	learn or modify	this error if
       desired.

       There is	also a "next_ops->reopen" function which is used by
       nbdkit-retry-filter(3) to close and reopen the underlying plugin.  It
       should be used with caution because it is difficult to use safely.

   Other considerations
       You can modify parameters when you call the "next" function.  However
       be careful when modifying strings because for some methods (eg.
       ".config") the plugin may save the string pointer that you pass along.
       So you may have to ensure that the string is not	freed for the lifetime
       of the server.

       Note that if your filter	registers a callback but in that callback it
       doesn't call the	"next" function	then the corresponding method in the
       plugin will never be called.  In	particular, your ".open" method, if
       you have	one, must call the ".next" method.

CALLBACKS
       "struct nbdkit_filter" has some static fields describing	the filter and
       optional	callback functions which can be	used to	intercept plugin
       methods.

   ".name"
	const char *name;

       This field (a string) is	required, and must contain only	ASCII
       alphanumeric characters and be unique amongst all filters.

   ".longname"
	const char *longname;

       An optional free	text name of the filter.  This field is	used in	error
       messages.

   ".description"
	const char *description;

       An optional multi-line description of the filter.

   ".load"
	void load (void);

       This is called once just	after the filter is loaded into	memory.	 You
       can use this to perform any global initialization needed	by the filter.

   ".unload"
	void unload (void);

       This may	be called once just before the filter is unloaded from memory.
       Note that it's not guaranteed that ".unload" will always	be called (eg.
       the server might	be killed or segfault),	so you should try to make the
       filter as robust	as possible by not requiring cleanup.  See also
       "SHUTDOWN" in nbdkit-plugin(3).

   ".config"
	int (*config) (nbdkit_next_config *next, void *nxdata,
		       const char *key,	const char *value);

       This intercepts the plugin ".config" method and can be used by the
       filter to parse its own command line parameters.	 You should try	to
       make sure that command line parameter keys that the filter uses do not
       conflict	with ones that could be	used by	a plugin.

       If there	is an error, ".config" should call "nbdkit_error" with an
       error message and return	"-1".

   ".config_complete"
	int (*config_complete) (nbdkit_next_config_complete *next, void	*nxdata);

       This intercepts the plugin ".config_complete" method and	can be used to
       ensure that all parameters needed by the	filter were supplied on	the
       command line.

       If there	is an error, ".config_complete"	should call "nbdkit_error"
       with an error message and return	"-1".

   ".config_help"
	const char *config_help;

       This optional multi-line	help message should summarize any "key=value"
       parameters that it takes.  It does not need to repeat what already
       appears in ".description".

       If the filter doesn't take any config parameters	you should probably
       omit this.

   ".thread_model"
	int (*thread_model) (void);

       Filters may tighten (but	not relax) the thread model of the plugin, by
       defining	this callback.	Note that while	plugins	use a compile-time
       definition of "THREAD_MODEL", filters do	not need to declare a model at
       compile time; instead, this callback is called after ".config_complete"
       and before any connections are created.	See "THREADS" in
       nbdkit-plugin(3)	for a discussion of thread models.

       The final thread	model used by nbdkit is	the smallest (ie. most
       serialized) out of all the filters and the plugin, and applies for all
       connections.  Requests for a model larger than permitted	by the plugin
       are silently ignored. It	is acceptable for decisions made during
       ".config" and ".config_complete"	to determine which model to request.

       This callback is	optional; if it	is not present,	the filter must	be
       written to handle fully parallel	requests, including when multiple
       requests	are issued in parallel on the same connection, similar to a
       plugin requesting "NBDKIT_THREAD_MODEL_PARALLEL".  This ensures the
       filter doesn't slow down	other filters or plugins.

       If there	is an error, ".thread_model" should call "nbdkit_error"	with
       an error	message	and return "-1".

   ".get_ready"
	int (*get_ready) (nbdkit_next_get_ready	*next, void *nxdata);

       This intercepts the plugin ".get_ready" method and can be used by the
       filter to get ready to serve requests.

       If there	is an error, ".get_ready" should call "nbdkit_error" with an
       error message and return	"-1".

   ".preconnect"
	int (*preconnect) (nbdkit_next_preconnect *next, void *nxdata,
			   int readonly);

       This intercepts the plugin ".preconnect"	method and can be used to
       filter access to	the server.

       If there	is an error, ".preconnect" should call "nbdkit_error" with an
       error message and return	"-1".

   ".open"
	void * (*open) (nbdkit_next_open *next,	void *nxdata,
			int readonly);

       This is called when a new client	connection is opened and can be	used
       to allocate any per-connection data structures needed by	the filter.
       The handle (which is not	the same as the	plugin handle) is passed back
       to other	filter callbacks and could be freed in the ".close" callback.

       Note that the handle is completely opaque to nbdkit, but	it must	not be
       NULL.  If you don't need	to use a handle, return
       "NBDKIT_HANDLE_NOT_NEEDED" which	is a static non-NULL pointer.

       If there	is an error, ".open" should call "nbdkit_error"	with an	error
       message and return "NULL".

       This callback is	optional, but if provided, it must call	"next",
       passing a value for "readonly" according	to how the filter plans	to use
       the plugin.  Typically, the filter passes the same value	as it
       received, or passes true	to provide a writable layer on top of a	read-
       only backend.  However, it is also acceptable to	attempt	write access
       to the plugin even if this filter is readonly, such as when a file
       system mounted read-only	still requires write access to the underlying
       device in case a	journal	needs to be replayed for consistency as	part
       of the mounting process.	 The filter should generally call "next" as
       its first step, to allocate from	the plugin outwards, so	that ".close"
       running from the	outer filter to	the plugin will	be in reverse.

   ".close"
	void (*close) (void *handle);

       This is called when the client closes the connection.  It should	clean
       up any per-connection resources used by the filter.  It is called
       beginning with the outermost filter and ending with the plugin (the
       opposite	order of ".open" if all	filters	call "next" first), although
       this order technically does not matter since the	callback cannot	report
       failures	or access the underlying plugin.

   ".prepare"
   ".finalize"
	 int (*prepare)	(struct	nbdkit_next_ops	*next_ops, void	*nxdata,
			 void *handle, int readonly);
	 int (*finalize) (struct nbdkit_next_ops *next_ops, void *nxdata,
			  void *handle);

       These two methods can be	used to	perform	any necessary operations just
       after opening the connection (".prepare") or just before	closing	the
       connection (".finalize").

       For example if you need to scan the underlying disk to check for	a
       partition table,	you could do it	in your	".prepare" method (calling the
       plugin's	".pread" method	via "next_ops").  Or if	you need to cleanly
       update superblock data in the image on close you	can do it in your
       ".finalize" method (calling the plugin's	".pwrite" method).  Doing
       these things in the filter's ".open" or ".close"	method is not
       possible.

       For ".prepare", the value of "readonly" is the same as was passed to
       ".open",	declaring how this filter will be used.

       There is	no "next_ops->prepare" or "next_ops->finalize".	 Unlike	other
       filter methods, prepare and finalize are	not chained through the
       "next_ops" structure.  Instead the core nbdkit server calls the prepare
       and finalize methods of all filters.  Prepare methods are called
       starting	with the filter	closest	to the plugin and proceeding outwards
       (matching the order of ".open" if all filters call "next" before	doing
       anything	locally).  Finalize methods are	called in the reverse order of
       prepare methods,	with the outermost filter first	(and matching the
       order of	".close"), and only if the prepare method succeeded.

       If there	is an error, both callbacks should call	"nbdkit_error" with an
       error message and return	"-1".  An error	in ".prepare" is reported to
       the client, but leaves the connection open (a client may	try again with
       a different export name,	for example); while an error in	".finalize"
       forces the client to disconnect.

   ".get_size"
	int64_t	(*get_size) (struct nbdkit_next_ops *next_ops, void *nxdata,
			     void *handle);

       This intercepts the plugin ".get_size" method and can be	used to	read
       or modify the apparent size of the block	device that the	NBD client
       will see.

       The returned size must be aY 0.	If there is an error, ".get_size"
       should call "nbdkit_error" with an error	message	and return "-1".  This
       function	is only	called once per	connection and cached by nbdkit.
       Similarly, repeated calls to "next_ops->get_size" will return a cached
       value.

   ".can_write"
   ".can_flush"
   ".is_rotational"
   ".can_trim"
   ".can_zero"
   ".can_fast_zero"
   ".can_extents"
   ".can_fua"
   ".can_multi_conn"
   ".can_cache"
	int (*can_write) (struct nbdkit_next_ops *next_ops, void *nxdata,
			  void *handle);
	int (*can_flush) (struct nbdkit_next_ops *next_ops, void *nxdata,
			  void *handle);
	int (*is_rotational) (struct nbdkit_next_ops *next_ops,
			      void *nxdata,
			      void *handle);
	int (*can_trim)	(struct	nbdkit_next_ops	*next_ops, void	*nxdata,
			 void *handle);
	int (*can_zero)	(struct	nbdkit_next_ops	*next_ops, void	*nxdata,
			 void *handle);
	int (*can_fast_zero) (struct nbdkit_next_ops *next_ops,	void *nxdata,
			      void *handle);
	int (*can_extents) (struct nbdkit_next_ops *next_ops, void *nxdata,
			    void *handle);
	int (*can_fua) (struct nbdkit_next_ops *next_ops, void *nxdata,
			void *handle);
	int (*can_multi_conn) (struct nbdkit_next_ops *next_ops, void *nxdata,
			       void *handle);
	int (*can_cache) (struct nbdkit_next_ops *next_ops, void *nxdata,
			  void *handle);

       These intercept the corresponding plugin	methods, and control feature
       bits advertised to the client.

       Of note,	the semantics of ".can_zero" callback in the filter are
       slightly	different from the plugin, and must be one of three success
       values visible only to filters:

       "NBDKIT_ZERO_NONE"
	   Completely suppress advertisement of	write zero support (this can
	   only	be done	from filters, not plugins).

       "NBDKIT_ZERO_EMULATE"
	   Inform nbdkit that write zeroes should immediately fall back	to
	   ".pwrite" emulation without trying ".zero" (this value is returned
	   by "next_ops->can_zero" if the plugin returned false	in its
	   ".can_zero").

       "NBDKIT_ZERO_NATIVE"
	   Inform nbdkit that write zeroes should attempt to use ".zero",
	   although it may still fall back to ".pwrite"	emulation for
	   "ENOTSUP" or	"EOPNOTSUPP" failures (this value is returned by
	   "next_ops->can_zero"	if the plugin returned true in its
	   ".can_zero").

       Remember	that most of the feature check functions return	merely a
       boolean success value, while ".can_zero", ".can_fua" and	".can_cache"
       have three success values.

       The difference between ".can_fua" values	may affect choices made	in the
       filter: when splitting a	write request that requested FUA from the
       client, if "next_ops->can_fua" returns "NBDKIT_FUA_NATIVE", then	the
       filter should pass the FUA flag on to each sub-request; while if	it is
       known that FUA is emulated by a flush because of	a return of
       "NBDKIT_FUA_EMULATE", it	is more	efficient to only flush	once after all
       sub-requests have completed (often by passing "NBDKIT_FLAG_FUA" on to
       only the	final sub-request, or by dropping the flag and ending with a
       direct call to "next_ops->flush").

       If there	is an error, the callback should call "nbdkit_error" with an
       error message and return	"-1".  These functions are called at most once
       per connection and cached by nbdkit. Similarly, repeated	calls to any
       of the "next_ops" counterparts will return a cached value; by calling
       into the	plugin during ".prepare", you can ensure that later use	of the
       cached values during data commands like <.pwrite> will not fail.

   ".pread"
	int (*pread) (struct nbdkit_next_ops *next_ops,	void *nxdata,
		      void *handle, void *buf, uint32_t	count, uint64_t	offset,
		      uint32_t flags, int *err);

       This intercepts the plugin ".pread" method and can be used to read or
       modify data read	by the plugin.

       The parameter "flags" exists in case of future NBD protocol extensions;
       at this time, it	will be	0 on input, and	the filter should not pass any
       flags to	"next_ops->pread".

       If there	is an error (including a short read which couldn't be
       recovered from),	".pread" should	call "nbdkit_error" with an error
       message and return -1 with "err"	set to the positive errno value	to
       return to the client.

   ".pwrite"
	int (*pwrite) (struct nbdkit_next_ops *next_ops, void *nxdata,
		       void *handle,
		       const void *buf,	uint32_t count,	uint64_t offset,
		       uint32_t	flags, int *err);

       This intercepts the plugin ".pwrite" method and can be used to modify
       data written by the plugin.

       This function will not be called	if ".can_write"	returned false;	in
       turn, the filter	should not call	"next_ops->pwrite" if
       "next_ops->can_write" did not return true.

       The parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on
       the result of ".can_fua".  In turn, the filter should only pass
       "NBDKIT_FLAG_FUA" on to "next_ops->pwrite" if "next_ops->can_fua"
       returned	a positive value.

       If there	is an error (including a short write which couldn't be
       recovered from),	".pwrite" should call "nbdkit_error" with an error
       message and return -1 with "err"	set to the positive errno value	to
       return to the client.

   ".flush"
	int (*flush) (struct nbdkit_next_ops *next_ops,	void *nxdata,
		      void *handle, uint32_t flags, int	*err);

       This intercepts the plugin ".flush" method and can be used to modify
       flush requests.

       This function will not be called	if ".can_flush"	returned false;	in
       turn, the filter	should not call	"next_ops->flush" if
       "next_ops->can_flush" did not return true.

       The parameter "flags" exists in case of future NBD protocol extensions;
       at this time, it	will be	0 on input, and	the filter should not pass any
       flags to	"next_ops->flush".

       If there	is an error, ".flush" should call "nbdkit_error" with an error
       message and return -1 with "err"	set to the positive errno value	to
       return to the client.

   ".trim"
	int (*trim) (struct nbdkit_next_ops *next_ops, void *nxdata,
		     void *handle, uint32_t count, uint64_t offset,
		     uint32_t flags, int *err);

       This intercepts the plugin ".trim" method and can be used to modify
       trim requests.

       This function will not be called	if ".can_trim" returned	false; in
       turn, the filter	should not call	"next_ops->trim" if
       "next_ops->can_trim" did	not return true.

       The parameter "flags" may include "NBDKIT_FLAG_FUA" on input based on
       the result of ".can_fua".  In turn, the filter should only pass
       "NBDKIT_FLAG_FUA" on to "next_ops->trim"	if "next_ops->can_fua"
       returned	a positive value.

       If there	is an error, ".trim" should call "nbdkit_error"	with an	error
       message and return -1 with "err"	set to the positive errno value	to
       return to the client.

   ".zero"
	int (*zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
		     void *handle, uint32_t count, uint64_t offset, uint32_t flags,
		     int *err);

       This intercepts the plugin ".zero" method and can be used to modify
       zero requests.

       This function will not be called	if ".can_zero" returned
       "NBDKIT_ZERO_NONE"; in turn, the	filter should not call
       "next_ops->zero"	if "next_ops->can_zero"	returned "NBDKIT_ZERO_NONE".

       On input, the parameter "flags" may include "NBDKIT_FLAG_MAY_TRIM"
       unconditionally,	"NBDKIT_FLAG_FUA" based	on the result of ".can_fua",
       and "NBDKIT_FLAG_FAST_ZERO" based on the	result of ".can_fast_zero".
       In turn,	the filter may pass "NBDKIT_FLAG_MAY_TRIM" unconditionally,
       but should only pass "NBDKIT_FLAG_FUA" or "NBDKIT_FLAG_FAST_ZERO" on to
       "next_ops->zero"	if the corresponding "next_ops->can_fua" or
       "next_ops->can_fast_zero" returned a positive value.

       Note that unlike	the plugin ".zero" which is permitted to fail with
       "ENOTSUP" or "EOPNOTSUPP" to force a fallback to	".pwrite", the
       function	"next_ops->zero" will not fail with "err" set to "ENOTSUP" or
       "EOPNOTSUPP" unless "NBDKIT_FLAG_FAST_ZERO" was used, because otherwise
       the fallback has	already	taken place.

       If there	is an error, ".zero" should call "nbdkit_error"	with an	error
       message and return -1 with "err"	set to the positive errno value	to
       return to the client.  The filter should	not fail with "ENOTSUP"	or
       "EOPNOTSUPP" unless "flags" includes "NBDKIT_FLAG_FAST_ZERO" (while
       plugins have automatic fallback to ".pwrite", filters do	not).

   ".extents"
	int (*extents) (struct nbdkit_next_ops *next_ops, void *nxdata,
			void *handle, uint32_t count, uint64_t offset, uint32_t	flags,
			struct nbdkit_extents *extents,
			int *err);

       This intercepts the plugin ".extents" method and	can be used to modify
       extent requests.

       This function will not be called	if ".can_extents" returned false; in
       turn, the filter	should not call	"next_ops->extents" if
       "next_ops->can_extents" did not return true.

       It is possible for filters to transform the extents list	received back
       from the	layer below.  Without error checking it	would look like	this:

	myfilter_extents (..., uint32_t	count, uint64_t	offset,	...)
	{
	  size_t i;
	  struct nbdkit_extents	*extents2;
	  struct nbdkit_extent e;
	  int64_t size;

	  size = next_ops->get_size (nxdata);
	  extents2 = nbdkit_extents_new	(offset	+ shift, size);
	  next_ops->extents (nxdata, count, offset + shift, flags, extents2, err);
	  for (i = 0; i	< nbdkit_extents_count (extents2); ++i)	{
	    e =	nbdkit_get_extent (extents2, i);
	    e.offset -=	shift;
	    nbdkit_add_extent (extents,	e.offset, e.length, e.type);
	  }
	  nbdkit_extents_free (extents2);
	}

       If there	is an error, ".extents"	should call "nbdkit_error" with	an
       error message and return	-1 with	"err" set to the positive errno	value
       to return to the	client.

       Allocating and freeing nbdkit_extents list

       Two functions are provided to filters only for allocating and freeing
       the map:

	struct nbdkit_extents *nbdkit_extents_new (uint64_t start, uint64_t end);

       Allocates and returns a new, empty extents list.	 The "start" parameter
       is the start of the range described in the list,	and the	"end"
       parameter is the	offset of the byte beyond the end.  Normally you would
       pass in "offset"	as the start and the size of the plugin	as the end,
       but for filters which adjust offsets, they should pass in the adjusted
       offset.

       On error	this function can return "NULL".  In this case it calls
       "nbdkit_error" and/or "nbdkit_set_error"	as required.  "errno" will be
       set to a	suitable value.

	void nbdkit_extents_free (struct nbdkit_extents	*);

       Frees an	existing extents list.

       Iterating over nbdkit_extents list

       Two functions are provided to filters only to iterate over the extents
       in order:

	size_t nbdkit_extents_count (const struct nbdkit_extents *);

       Returns the number of extents in	the list.

	struct nbdkit_extent {
	  uint64_t offset;
	  uint64_t length;
	  uint32_t type;
	};
	struct nbdkit_extent nbdkit_get_extent (const struct nbdkit_extents *,
						size_t i);

       Returns a copy of the "i"'th extent.

   ".cache"
	int (*cache) (struct nbdkit_next_ops *next_ops,	void *nxdata,
		      void *handle, uint32_t count, uint64_t offset,
		      uint32_t flags, int *err);

       This intercepts the plugin ".cache" method and can be used to modify
       cache requests.

       This function will not be called	if ".can_cache"	returned
       "NBDKIT_CACHE_NONE" or "NBDKIT_CACHE_EMULATE"; in turn, the filter
       should not call "next_ops->cache" unless	"next_ops->can_cache" returned
       "NBDKIT_CACHE_NATIVE".

       The parameter "flags" exists in case of future NBD protocol extensions;
       at this time, it	will be	0 on input, and	the filter should not pass any
       flags to	"next_ops->cache".

       If there	is an error, ".cache" should call "nbdkit_error" with an error
       message and return -1 with "err"	set to the positive errno value	to
       return to the client.

ERROR HANDLING
       If there	is an error in the filter itself, the filter should call
       "nbdkit_error" to report	an error message.  If the callback is involved
       in serving data,	the explicit "err" parameter determines	the error code
       that will be sent to the	client;	other callbacks	should return the
       appropriate error indication, eg. "NULL"	or "-1".

       "nbdkit_error" has the following	prototype and works like printf(3):

	void nbdkit_error (const char *fs, ...);
	void nbdkit_verror (const char *fs, va_list args);

       For convenience,	"nbdkit_error" preserves the value of "errno", and
       also supports the glibc extension of a single %m	in a format string
       expanding to "strerror(errno)", even on platforms that don't support
       that natively.

DEBUGGING
       Run the server with -f and -v options so	it doesn't fork	and you	can
       see debugging information:

	nbdkit -fv --filter=./myfilter.so plugin [key=value [key=value [...]]]

       To print	debugging information from within the filter, call
       "nbdkit_debug", which has the following prototype and works like
       printf(3):

	void nbdkit_debug (const char *fs, ...);
	void nbdkit_vdebug (const char *fs, va_list args);

       For convenience,	"nbdkit_debug" preserves the value of "errno", and
       also supports the glibc extension of a single %m	in a format string
       expanding to "strerror(errno)", even on platforms that don't support
       that natively.  Note that "nbdkit_debug"	only prints things when	the
       server is in verbose mode (-v option).

   Debug Flags
       Debug Flags in filters work exactly the same way	as plugins.  See
       "Debug Flags" in	nbdkit-plugin(3).

INSTALLING THE FILTER
       The filter is a "*.so" file and possibly	a manual page.	You can	of
       course install the filter "*.so"	file wherever you want,	and users will
       be able to use it by running:

	nbdkit --filter=/path/to/filter.so plugin [args]

       However if the shared library has a name	of the form
       "nbdkit-name-filter.so" and if the library is installed in the
       $filterdir directory, then users	can be run it by only typing:

	nbdkit --filter=name plugin [args]

       The location of the $filterdir directory	is set when nbdkit is compiled
       and can be found	by doing:

	nbdkit --dump-config

       If using	the pkg-config/pkgconf system then you can also	find the
       filter directory	at compile time	by doing:

	pkg-config nbdkit --variable=filterdir

PKG-CONFIG/PKGCONF
       nbdkit provides a pkg-config/pkgconf file called	"nbdkit.pc" which
       should be installed on the correct path when the	nbdkit development
       environment is installed.  You can use this in autoconf configure.ac
       scripts to test for the development environment:

	PKG_CHECK_MODULES([NBDKIT], [nbdkit >= 1.2.3])

       The above will fail unless nbdkit aY 1.2.3 and the header file is
       installed, and will set "NBDKIT_CFLAGS" and "NBDKIT_LIBS" appropriately
       for compiling filters.

       You can also run	pkg-config/pkgconf directly, for example:

	if ! pkg-config	nbdkit --exists; then
	  echo "you must install the nbdkit development	environment"
	  exit 1
	fi

       You can also substitute the filterdir variable by doing:

	PKG_CHECK_VAR([NBDKIT_FILTERDIR], [nbdkit], [filterdir])

       which defines "$(NBDKIT_FILTERDIR)" in automake-generated Makefiles.

SEE ALSO
       nbdkit(1), nbdkit-plugin(3).

       Standard	filters	provided by nbdkit:

       nbdkit-blocksize-filter(1), nbdkit-cache-filter(1),
       nbdkit-cacheextents-filter(1), nbdkit-cow-filter(1),
       nbdkit-delay-filter(1), nbdkit-error-filter(1),
       nbdkit-exitlast-filter(1), nbdkit-ext2-filter(1),
       nbdkit-extentlist-filter(1), nbdkit-fua-filter(1), nbdkit-ip-filter(1),
       nbdkit-limit-filter(1), nbdkit-log-filter(1), nbdkit-nocache-filter(1),
       nbdkit-noextents-filter(1), nbdkit-nofilter-filter(1),
       nbdkit-noparallel-filter(1), nbdkit-nozero-filter(1),
       nbdkit-offset-filter(1),	nbdkit-partition-filter(1),
       nbdkit-rate-filter(1), nbdkit-readahead-filter(1),
       nbdkit-retry-filter(1), nbdkit-stats-filter(1),
       nbdkit-truncate-filter(1), nbdkit-xz-filter(1) .

AUTHORS
       Eric Blake

       Richard W.M. Jones

COPYRIGHT
       Copyright (C) 2013-2020 Red Hat Inc.

LICENSE
       Redistribution and use in source	and binary forms, with or without
       modification, are permitted provided that the following conditions are
       met:

       o   Redistributions of source code must retain the above	copyright
	   notice, this	list of	conditions and the following disclaimer.

       o   Redistributions in binary form must reproduce the above copyright
	   notice, this	list of	conditions and the following disclaimer	in the
	   documentation and/or	other materials	provided with the
	   distribution.

       o   Neither the name of Red Hat nor the names of	its contributors may
	   be used to endorse or promote products derived from this software
	   without specific prior written permission.

       THIS SOFTWARE IS	PROVIDED BY RED	HAT AND	CONTRIBUTORS ''AS IS'' AND ANY
       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
       LIABLE FOR ANY DIRECT, INDIRECT,	INCIDENTAL, SPECIAL, EXEMPLARY,	OR
       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
       SUBSTITUTE GOODS	OR SERVICES; LOSS OF USE, DATA,	OR PROFITS; OR
       BUSINESS	INTERRUPTION) HOWEVER CAUSED AND ON ANY	THEORY OF LIABILITY,
       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
       OTHERWISE) ARISING IN ANY WAY OUT OF THE	USE OF THIS SOFTWARE, EVEN IF
       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

nbdkit-1.20.4			  2021-03-01		      nbdkit-filter(3)

NAME | SYNOPSIS | DESCRIPTION | "#include <nbdkit-filter.h>" | "struct nbdkit_filter" | NEXT PLUGIN | CALLBACKS | ERROR HANDLING | DEBUGGING | INSTALLING THE FILTER | PKG-CONFIG/PKGCONF | SEE ALSO | AUTHORS | COPYRIGHT | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=nbdkit-filter&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help