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

FreeBSD Manual Pages

  
 
  

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

NAME
       nbdkit-plugin - how to write nbdkit plugins

SYNOPSIS
	#define	NBDKIT_API_VERSION 2
	#include <nbdkit-plugin.h>

	#define	THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS

	static void *
	myplugin_open (void)
	{
	  /* create a handle ... */
	  return handle;
	}

	static struct nbdkit_plugin plugin = {
	  .name		     = "myplugin",
	  .open		     = myplugin_open,
	  .get_size	     = myplugin_get_size,
	  .pread	     = myplugin_pread,
	  .pwrite	     = myplugin_pwrite,
	  /* etc */
	};
	NBDKIT_REGISTER_PLUGIN(plugin)

       Compile the plugin as a shared library:

	gcc -fPIC -shared myplugin.c -o	myplugin.so

       and load	it into	nbdkit:

	nbdkit [--args ...] ./myplugin.so [key=value ...]

       When debugging, use the -fv options:

	nbdkit -fv ./myplugin.so [key=value ...]

DESCRIPTION
       An nbdkit plugin	is a new source	device which can be served using the
       Network Block Device (NBD) protocol.  This manual page describes	how to
       create an nbdkit	plugin in C.

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

       To write	plugins	in other languages, see: nbdkit-golang-plugin(3),
       nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3),
       nbdkit-python-plugin(3),	nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3),
       nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .

   API and ABI guarantee for C plugins
       Plugins written in C have an ABI	guarantee: a plugin compiled against
       an older	version	of nbdkit will still work correctly when loaded	with a
       newer nbdkit.  We also try (but cannot guarantee) to support plugins
       compiled	against	a newer	version	of nbdkit when loaded with an older
       nbdkit, although	the plugin may have reduced functionality if it
       depends on features only	provided by newer nbdkit.

       For plugins written in C, we also provide an API	guarantee: a plugin
       written against an older	header will still compile unmodified with a
       newer nbdkit.

       The API guarantee does not always apply to plugins written in other
       (non-C) languages which may have	to adapt to changes when recompiled
       against a newer nbdkit.

WRITING	AN NBDKIT PLUGIN
   "#define NBDKIT_API_VERSION 2"
       Plugins must choose which API version they want to use, by defining
       NBDKIT_API_VERSION before including "<nbdkit-plugin.h>" (or any other
       nbdkit header).

       If omitted, the default version is 1 for	backwards-compatibility	with
       nbdkit v1.1.26 and earlier; however, it is recommended that new plugins
       be written to the maximum version (currently 2) as it enables more
       features	and better interaction with nbdkit filters.

       The rest	of this	document only covers the version 2 interface.  A newer
       nbdkit will always support plugins written in C which use any prior API
       version.

   "#include <nbdkit-plugin.h>"
       All plugins should start	by including this header file (after
       optionally choosing an API version).

   "#define THREAD_MODEL ..."
       All plugins must	define a thread	model.	See "Threads" below for
       details.	 It is generally safe to use:

	#define	THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS

   "struct nbdkit_plugin"
       All plugins must	define and register one	"struct	nbdkit_plugin",	which
       contains	the name of the	plugin and pointers to callback	functions, and
       use the "NBDKIT_REGISTER_PLUGIN(plugin)"	macro:

	static struct nbdkit_plugin plugin = {
	  .name		     = "myplugin",
	  .longname	     = "My Plugin",
	  .description	     = "This is	my great plugin	for nbdkit",
	  .open		     = myplugin_open,
	  .get_size	     = myplugin_get_size,
	  .pread	     = myplugin_pread,
	  .pwrite	     = myplugin_pwrite,
	  /* etc */
	};
	NBDKIT_REGISTER_PLUGIN(plugin)

       The ".name" field is the	name of	the plugin.

       The callbacks are described below (see "CALLBACKS").  Only ".name",
       ".open",	".get_size" and	".pread" are required.	All other callbacks
       can be omitted, although	typical	plugins	need to	use more.

   Callback lifecycle
       Callbacks are called in the following order over	the lifecycle of the
       plugin:

		aaaaaaaaaaaaaaaaaaaa
		a load		   a
		aaaaaaaaaaa~aaaaaaaaa
			  a	      configuration phase starts     aa
		aaaaaaaaaaa'aaaaaaaaa				       a
		a config	   a  config is	called once per	      a
		aaaaaaaaaaa~aaaaaaaaaao	key=value on the command line	a
		aaaaaaaaaaa'aaaaaaaaa				       a
		a config_complete  a				      a
		aaaaaaaaaaa~aaaaaaaaa				       a
		aaaaaaaaaaa'aaaaaaaaa				       a
		a thread_model	   a				      a
		aaaaaaaaaaa~aaaaaaaaa  configuration phase ends	      aa
		aaaaaaaaaaa'aaaaaaaaa
		a get_ready	   a
		aaaaaaaaaaa~aaaaaaaaa
			  a	      nbdkit forks into	the background
			  a	      and starts serving clients
			  a
	       aaaaaaaaaaaa'aaaaaaaaaaaaaa~a a a a a a a a a
	aaaaaaaa'aaaaaa	client #1	 a
	a preconnect a			a
	aaaaaaaa~aaaaaa			 a
	aaaaaaaa'aaaaaa			 a
	a open	     a			a
	aaaaaaaa~aaaaaa			 a
	aaaaaaaa'aaaaaa	 NBD option	 a
	a can_write  a	negotiation	a
	aaaaaaaa~aaaaaa			 a
	aaaaaaaa'aaaaaa		  aaaaaaaa'aaaaaa client #2
	a get_size   a		 a preconnect a
	aaaaaaaa~aaaaaa		  aaaaaaaa~aaaaaa
	aaaaaaaa'aaaaaa	data	  aaaaaaaa'aaaaaa
	a pread	     a serving	 a open	      a
	aaaaaaaa~aaaaaaao	   aaaaaaaa~aaaaaa
	aaaaaaaa'aaaaaa			...
	a pwrite     a
	aaaaaaaa~aaaaaaao	   aaaaaaaa'aaaaaa
	aaaaaaaa'aaaaaa		  a close      a
	a close	     a		 aaaaaaaaaaaaaa
	aaaaaaaaaaaaaa

			  a	      before nbdkit exits
			  a
		aaaaaaaaaaa'aaaaaaaaa
		a unload	   a
		aaaaaaaaaaaaaaaaaaaa

       ".load"
	   is called once just after the plugin	is loaded into memory.

       ".config" and ".config_complete"
	   ".config" is	called zero or more times during command line parsing.
	   ".config_complete" is called	once after all configuration
	   information has been	passed to the plugin (but not during "nbdkit
	   --dump-plugin").

	   Both	are called after loading the plugin but	before any connections
	   are accepted.

       ".thread_model"
	   In normal operation,	".thread_model"	is called once after
	   ".config_complete" has validated all	configuration information, and
	   before any connections are accepted.	 However, during "nbdkit
	   --dump-plugin", it is called	after any ".config" calls but without
	   ".config_complete" (so a plugin which determines the	results	from a
	   script must be prepared for a missing script).

       ".get_ready"
	   In normal operation,	".get_ready" is	called before the server
	   starts serving.  It is called before	the server forks or changes
	   directory.  It is the last chance to	do any global preparation that
	   is needed to	serve connections.

       ".preconnect"
	   Called when a TCP connection	has been made to the server.  This
	   happens early, before NBD or	TLS negotiation.

       ".open"
	   A new client	has connected and finished the NBD handshake.  TLS
	   negotiation (if required) has been completed	successfully.

       ".can_write", ".get_size" and other option negotiation callbacks
	   These are called during option negotiation with the client, but
	   before any data is served.  These callbacks may return different
	   values across different ".open" calls, but within a single
	   connection, they are	called at most once and	cached by nbdkit for
	   that	connection.

       ".pread", ".pwrite" and other data serving callbacks
	   After option	negotiation has	finished, these	may be called to serve
	   data.  Depending on the thread model	chosen,	they might be called
	   in parallel from multiple threads.  The data	serving	callbacks
	   include a flags argument; the results of the	negotiation callbacks
	   influence whether particular	flags will ever	be passed to a data
	   callback.

       ".close"
	   The client has disconnected.

       ".preconnect", ".open" ... ".close"
	   The sequence	".preconnect", ".open" ... ".close" can	be called
	   repeatedly over the lifetime	of the plugin, and can be called in
	   parallel (depending on the thread model).

       ".unload"
	   is called once just before the plugin is unloaded from memory.

   Flags
       The following flags are defined by nbdkit, and used in various data
       serving callbacks as follows:

       "NBDKIT_FLAG_MAY_TRIM"
	   This	flag is	used by	the ".zero" callback; there is no way to
	   disable this	flag, although a plugin	that does not support trims as
	   a way to write zeroes may ignore the	flag without violating
	   expected semantics.

       "NBDKIT_FLAG_FUA"
	   This	flag represents	Forced Unit Access semantics.  It is used by
	   the ".pwrite", ".zero", and ".trim" callbacks to indicate that the
	   plugin must not return a result until the action has	landed in
	   persistent storage.	This flag will not be sent to the plugin
	   unless ".can_fua" is	provided and returns "NBDKIT_FUA_NATIVE".

       The following defines are valid as successful return values for
       ".can_fua":

       "NBDKIT_FUA_NONE"
	   Forced Unit Access is not supported;	the client must	manually
	   request a flush after writes	have completed.	 The "NBDKIT_FLAG_FUA"
	   flag	will not be passed to the plugin's write callbacks.

       "NBDKIT_FUA_EMULATE"
	   The client may request Forced Unit Access, but it is	implemented by
	   emulation, where nbdkit calls ".flush" after	a write	operation;
	   this	is semantically	correct, but may hurt performance as it	tends
	   to flush more data than just	what the client	requested.  The
	   "NBDKIT_FLAG_FUA" flag will not be passed to	the plugin's write
	   callbacks.

       "NBDKIT_FUA_NATIVE"
	   The client may request Forced Unit Access, which results in the
	   "NBDKIT_FLAG_FUA" flag being	passed to the plugin's write callbacks
	   (".pwrite", ".trim",	and ".zero").  When the	flag is	set, these
	   callbacks must not return success until the client's	request	has
	   landed in persistent	storage.

       The following defines are valid as successful return values for
       ".can_cache":

       "NBDKIT_CACHE_NONE"
	   The server does not advertise caching support, and rejects any
	   client-requested caching. Any ".cache" callback is ignored.

       "NBDKIT_CACHE_EMULATE"
	   The nbdkit server advertises	cache support to the client, where the
	   client may request that the server cache a region of	the export to
	   potentially speed up	future read and/or write operations on that
	   region. The nbdkit server implements	the caching by calling
	   ".pread" and	ignoring the results. This option exists to ease the
	   implementation of a common form of caching; any ".cache" callback
	   is ignored.

       "NBDKIT_CACHE_NATIVE"
	   The nbdkit server advertises	cache support to the client, where the
	   client may request that the server cache a region of	the export to
	   potentially speed up	future read and/or write operations on that
	   region. The nbdkit server calls the ".cache"	callback to perform
	   the caching;	if that	callback is missing, the client's cache
	   request succeeds without doing anything.

   Threads
       Each nbdkit plugin must declare its maximum thread safety model by
       defining	the "THREAD_MODEL" macro.  (This macro is used by
       "NBDKIT_REGISTER_PLUGIN").  Additionally, a plugin may implement	the
       ".thread_model" callback, called	right after ".config_complete" to make
       a runtime decision on which thread model	to use.	 The nbdkit server
       chooses the most	restrictive model between the plugin's "THREAD_MODEL",
       the ".thread_model" if present, any restrictions	requested by filters,
       and any limitations imposed by the operating system.

       In "nbdkit --dump-plugin	PLUGIN"	output,	the "max_thread_model" line
       matches the "THREAD_MODEL" macro, and the "thread_model"	line matches
       what the	system finally settled on after	applying all restrictions.

       The possible settings for "THREAD_MODEL"	are defined below.

       "#define	THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_CONNECTIONS"
	   Only	a single handle	can be open at any time, and all requests
	   happen from one thread.

	   Note	this means only	one client can connect to the server at	any
	   time.  If a second client tries to connect it will block waiting
	   for the first client	to close the connection.

       "#define	THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS"
	   This	is a safe default for most plugins.

	   Multiple handles can	be open	at the same time, but requests are
	   serialized so that for the plugin as	a whole	only one
	   open/read/write/close (etc) request will be in progress at any
	   time.

	   This	is a useful setting if the library you are using is not
	   thread-safe.	 However performance may not be	good.

       "#define	THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_REQUESTS"
	   Multiple handles can	be open	and multiple data requests can happen
	   in parallel.	 However only one request will happen per handle at a
	   time	(but requests on different handles might happen	concurrently).

       "#define	THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL"
	   Multiple handles can	be open	and multiple data requests can happen
	   in parallel (even on	the same handle).  The server may reorder
	   replies, answering a	later request before an	earlier	one.

	   All the libraries you use must be thread-safe and reentrant,	and
	   any code that creates a file	descriptor should atomically set
	   "FD_CLOEXEC"	if you do not want it accidentally leaked to another
	   thread's child process.  You	may also need to provide mutexes for
	   fields in your connection handle.

       If none of the above thread models are suitable,	use
       "NBDKIT_THREAD_MODEL_PARALLEL" and implement your own locking using
       "pthread_mutex_t" etc.

   Error handling
       If there	is an error in the plugin, the plugin should call
       "nbdkit_error" to report	an error message; additionally,	if the
       callback	is involved in serving data, the plugin	should call
       "nbdkit_set_error" to influence the error code that will	be sent	to the
       client.	These two functions can	be called in either order.  Then, the
       callback	should return the appropriate error indication,	eg. "NULL" or
       "-1".

       If the call to "nbdkit_set_error" is omitted while serving data,	then
       the global variable "errno" may be used.	 For plugins which have
       ".errno_is_preserved != 0" the core code	will use "errno".  In plugins
       written in non-C	languages, we usually cannot trust that	"errno"	will
       not be overwritten when returning from that language to C.  In that
       case, either the	plugin must call "nbdkit_set_error" or hard-coded
       "EIO" is	used.

       "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.

       "nbdkit_set_error" can be called	at any time, but only has an impact
       during callbacks	for serving data, and only when	the callback returns
       an indication of	failure.  It has the following prototype:

	void nbdkit_set_error (int err);

CALLBACKS
   ".name"
	const char *name;

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

   ".version"
	const char *version;

       Plugins may optionally set a version string which is displayed in help
       and debugging output.

   ".longname"
	const char *longname;

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

   ".description"
	const char *description;

       An optional multi-line description of the plugin.

   ".load"
	void load (void);

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

   ".unload"
	void unload (void);

       This may	be called once just before the plugin 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
       plugin as robust	as possible by not requiring cleanup.  See also
       "SHUTDOWN" below.

   ".dump_plugin"
	void dump_plugin (void);

       This optional callback is called	when the
       "nbdkitA	pluginA	--dump-plugin" command is used.	 It should print any
       additional informative "key=value" fields to stdout as needed.
       Prefixing the keys with the name	of the plugin will avoid conflicts.

   ".config"
	int config (const char *key, const char	*value);

       On the nbdkit command line, after the plugin filename, come an optional
       list of "key=value" arguments.  These are passed	to the plugin through
       this callback when the plugin is	first loaded and before	any
       connections are accepted.

       This callback may be called zero	or more	times.

       Both "key" and "value" parameters will be non-NULL.  The	strings	are
       owned by	nbdkit but will	remain valid for the lifetime of the plugin,
       so the plugin does not need to copy them.

       The key will be a non-empty string beginning with an ASCII alphabetic
       character ("A-Z"	"a-z").	 The rest of the key must contain only ASCII
       alphanumeric plus period, underscore or dash characters ("A-Z" "a-z"
       "0-9" "." "_" "-").  The	value may be an	arbitrary string, including an
       empty string.

       The names of "key"s accepted by plugins is up to	the plugin, but	you
       should probably look at other plugins and follow	the same conventions.

       If the value is a relative path,	then note that the server changes
       directory when it starts	up.  See "FILENAMES AND	PATHS" above.

       If "nbdkit_stdio_safe" returns 1, the value of the configuration
       parameter may be	used to	trigger	reading	additional data	through	stdin
       (such as	a password or inline script).

       If the ".config"	callback is not	provided by the	plugin,	and the	user
       tries to	specify	any "key=value"	arguments, then	nbdkit will exit with
       an error.

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

   ".magic_config_key"
	const char *magic_config_key;

       This optional string can	be used	to set a "magic" key used when parsing
       plugin parameters.  It affects how "bare	parameters" (those which do
       not contain an "=" character) are parsed	on the command line.

       If "magic_config_key != NULL" then any bare parameters are passed to
       the ".config" method as:	"configA (magic_config_key,A argv[i]);".

       If "magic_config_key" is	not set	then we	behave as in nbdkit < 1.7: If
       the first parameter on the command line is bare then it is passed to
       the ".config" method as:	"configA ("script",A value);".	Any other bare
       parameters give errors.

   ".config_complete"
	int config_complete (void);

       This optional callback is called	after all the configuration has	been
       passed to the plugin.  It is a good place to do checks, for example
       that the	user has passed	the required parameters	to the plugin.

       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 plugin doesn't take any config parameters	you should probably
       omit this.

   ".thread_model"
	int thread_model (void)

       This optional callback is called	after all the configuration has	been
       passed to the plugin.  It can be	used to	force a	stricter thread	model
       based on	configuration, compared	to "THREAD_MODEL".  See	"Threads"
       above for details.  Attempts to request a looser	(more parallel)	model
       are silently ignored.

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

   ".get_ready"
	int get_ready (void);

       This optional callback is called	before the server starts serving.  It
       is called before	the server forks or changes directory.	It is the last
       chance to do any	global preparation that	is needed to serve
       connections.

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

   ".preconnect"
	int preconnect (int readonly);

       This optional callback is called	when a TCP connection has been made to
       the server.  This happens early,	before NBD or TLS negotiation.	If TLS
       authentication is required to access the	server,	then it	has not	been
       negotiated at this point.

       For security reasons (to	avoid denial of	service	attacks) this callback
       should be written to be as fast and take	as few resources as possible.
       If you use this callback, only use it to	do basic access	control, such
       as checking "nbdkit_peer_name" against a	whitelist (see "PEER NAME" and
       nbdkit-ip-filter(1)).  It may be	better to do access control outside
       the server, for example using TCP wrappers or a firewall.

       The "readonly" flag informs the plugin that the server was started with
       the -r flag on the command line.

       Returning 0 will	allow the connection to	continue.  If there is an
       error or	you want to deny the connection, call "nbdkit_error" with an
       error message and return	"-1".

   ".open"
	void *open (int	readonly);

       This is called when a new client	connects to the	nbdkit server.	The
       callback	should allocate	a handle and return it.	 This handle is	passed
       back to other 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.

       The "readonly" flag informs the plugin that the server was started with
       the -r flag on the command line which forces connections	to be read-
       only.  Note that	the plugin may additionally force the connection to be
       readonly	(even if this flag is false) by	returning false	from the
       ".can_write" callback.  So if your plugin can only serve	read-only, you
       can ignore this parameter.

       This callback is	called after the NBD handshake has completed, which
       includes	TLS authentication (if required).  If the plugin defines a
       ".preconnect" callback, then it must be called and return with success
       before ".open" is called.

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

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

       This is called when the client closes the connection.  It should	clean
       up any per-connection resources.

       Note there is no	way in the NBD protocol	to communicate close errors
       back to the client, for example if your plugin calls close(2) and you
       are checking for	errors (as you should do).  Therefore the best you can
       do is to	log the	error on the server.  Well-behaved NBD clients should
       try to flush the	connection before it is	closed and check for errors,
       but obviously this is outside the scope of nbdkit.

   ".get_size"
	int64_t	get_size (void *handle);

       This is called during the option	negotiation phase of the protocol to
       get the size (in	bytes) of the block device being exported.

       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".

   ".can_write"
	int can_write (void *handle);

       This is called during the option	negotiation phase to find out if the
       handle supports writes.

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

       This callback is	not required.  If omitted, then	we return true iff a
       ".pwrite" callback has been defined.

   ".can_flush"
	int can_flush (void *handle);

       This is called during the option	negotiation phase to find out if the
       handle supports the flush-to-disk operation.

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

       This callback is	not required.  If omitted, then	we return true iff a
       ".flush"	callback has been defined.

   ".is_rotational"
	int is_rotational (void	*handle);

       This is called during the option	negotiation phase to find out if the
       backing disk is a rotational medium (like a traditional hard disk) or
       not (like an SSD).  If true, this may cause the client to reorder
       requests	to make	them more efficient for	a slow rotating	disk.

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

       This callback is	not required.  If omitted, then	we return false.

   ".can_trim"
	int can_trim (void *handle);

       This is called during the option	negotiation phase to find out if the
       plugin supports the trim/discard	operation for punching holes in	the
       backing storage.

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

       This callback is	not required.  If omitted, then	we return true iff a
       ".trim" callback	has been defined.

   ".can_zero"
	int can_zero (void *handle);

       This is called during the option	negotiation phase to find out if the
       plugin wants the	".zero"	callback to be utilized.  Support for writing
       zeroes is still advertised to the client	(unless	the
       nbdkit-nozero-filter(1) is also used), so returning false merely	serves
       as a way	to avoid complicating the ".zero" callback to have to fail
       with "ENOTSUP" or "EOPNOTSUPP" on the connections where it will never
       be more efficient than using ".pwrite" up front.

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

       This callback is	not required.  If omitted, then	for a normal zero
       request,	nbdkit always tries ".zero" first if it	is present, and
       gracefully falls	back to	".pwrite" if ".zero" was absent	or failed with
       "ENOTSUP" or "EOPNOTSUPP".

   ".can_fast_zero"
	int can_fast_zero (void	*handle);

       This is called during the option	negotiation phase to find out if the
       plugin wants to advertise support for fast zero requests.  If this
       support is not advertised, a client cannot attempt fast zero requests,
       and has no way to tell if writing zeroes	offers any speedups compared
       to using	".pwrite" (other than compressed network traffic).  If support
       is advertised, then ".zero" will	have "NBDKIT_FLAG_FAST_ZERO" set when
       the client has requested	a fast zero, in	which case the plugin must
       fail with "ENOTSUP" or "EOPNOTSUPP" up front if the request would not
       offer any benefits over ".pwrite".  Advertising support for fast	zero
       requests	does not require that writing zeroes be	fast, only that	the
       result (whether success or failure) is fast, so this should be
       advertised when feasible.

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

       This callback is	not required.  If omitted, then	nbdkit returns true if
       ".zero" is absent or ".can_zero"	returns	false (in those	cases, nbdkit
       fails all fast zero requests, as	its fallback to	".pwrite" is not
       inherently faster), otherwise false (since it cannot be determined in
       advance if the plugin's ".zero" will properly honor the semantics of
       "NBDKIT_FLAG_FAST_ZERO").

   ".can_extents"
	int can_extents	(void *handle);

       This is called during the option	negotiation phase to find out if the
       plugin supports detecting allocated (non-sparse)	regions	of the disk
       with the	".extents" callback.

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

       This callback is	not required.  If omitted, then	we return true iff a
       ".extents" callback has been defined.

   ".can_fua"
	int can_fua (void *handle);

       This is called during the option	negotiation phase to find out if the
       plugin supports the Forced Unit Access (FUA) flag on write, zero, and
       trim requests.  If this returns "NBDKIT_FUA_NONE", FUA support is not
       advertised to the client; if this returns "NBDKIT_FUA_EMULATE", the
       ".flush"	callback must work (even if ".can_flush" returns false), and
       FUA support is emulated by calling ".flush" after any write operation;
       if this returns "NBDKIT_FUA_NATIVE", then the ".pwrite",	".zero", and
       ".trim" callbacks (if implemented) must handle the flag
       "NBDKIT_FLAG_FUA", by not returning until that action has landed	in
       persistent storage.

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

       This callback is	not required unless a plugin wants to specifically
       handle FUA requests.  If	omitted, nbdkit	checks whether ".flush"
       exists, and behaves as if this function returns "NBDKIT_FUA_NONE" or
       "NBDKIT_FUA_EMULATE" as appropriate.

   ".can_multi_conn"
	int can_multi_conn (void *handle);

       This is called during the option	negotiation phase to find out if the
       plugin is prepared to handle multiple connections from a	single client.
       If the plugin sets this to true then a client may try to	open multiple
       connections to the nbdkit server	and spread requests across all
       connections to maximize parallelism.  If	the plugin sets	it to false
       (which is the default) then well-behaved	clients	should only open a
       single connection, although we cannot control what clients do in
       practice.

       Specifically it means that either the plugin does not cache requests at
       all.  Or	if it does cache them then the effects of a ".flush" request
       or setting "NBDKIT_FLAG_FUA" on a request must be visible across	all
       connections to the plugin before	the plugin replies to that request.

       Properly	working	clients	should send the	same export name for each of
       these connections.

       If you use Linux	nbd-client(8) option -C_A num with numA >A 1 then Linux
       checks this flag	and will refuse	to connect if ".can_multi_conn"	is
       false.

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

       This callback is	not required.  If omitted, then	we return false.

   ".can_cache"
	int can_cache (void *handle);

       This is called during the option	negotiation phase to find out if the
       plugin supports a cache operation. The nature of	the caching is
       unspecified (including whether there are	limits on how much can be
       cached at once, and whether writes to a cached region have write-
       through or write-back semantics), but the command exists	to let clients
       issue a hint to the server that they will be accessing that region of
       the export.

       If this returns "NBDKIT_CACHE_NONE", cache support is not advertised to
       the client; if this returns "NBDKIT_CACHE_EMULATE", caching is emulated
       by the server calling ".pread" and ignoring the results;	if this
       returns "NBDKIT_CACHE_NATIVE", then the ".cache"	callback will be used.
       If there	is an error, ".can_cache" should call "nbdkit_error" with an
       error message and return	"-1".

       This callback is	not required.  If omitted, then	we return
       "NBDKIT_CACHE_NONE" if the ".cache" callback is missing,	or
       "NBDKIT_CACHE_NATIVE" if	it is defined.

   ".pread"
	int pread (void	*handle, void *buf, uint32_t count, uint64_t offset,
		   uint32_t flags);

       During the data serving phase, nbdkit calls this	callback to read data
       from the	backing	store.	"count"	bytes starting at "offset" in the
       backing store should be read and	copied into "buf".  nbdkit takes care
       of all bounds- and sanity-checking, so the plugin does not need to
       worry about that.

       The parameter "flags" exists in case of future NBD protocol extensions;
       at this time, it	will be	0 on input.

       The callback must read the whole	"count"	bytes if it can.  The NBD
       protocol	doesn't	allow partial reads (instead, these would be errors).
       If the whole "count" bytes was read, the	callback should	return 0 to
       indicate	there was no error.

       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 "nbdkit_set_error" to record an appropriate	error (unless
       "errno" is sufficient), then return "-1".

   ".pwrite"
	int pwrite (void *handle, const	void *buf, uint32_t count, uint64_t offset,
		    uint32_t flags);

       During the data serving phase, nbdkit calls this	callback to write data
       to the backing store.  "count" bytes starting at	"offset" in the
       backing store should be written using the data in "buf".	 nbdkit	takes
       care of all bounds- and sanity-checking,	so the plugin does not need to
       worry about that.

       This function will not be called	if ".can_write"	returned false.	 The
       parameter "flags" may include "NBDKIT_FLAG_FUA" on input	based on the
       result of ".can_fua".

       The callback must write the whole "count" bytes if it can.  The NBD
       protocol	doesn't	allow partial writes (instead, these would be errors).
       If the whole "count" bytes was written successfully, the	callback
       should return 0 to indicate there was no	error.

       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 "nbdkit_set_error" to record an appropriate	error (unless
       "errno" is sufficient), then return "-1".

   ".flush"
	int flush (void	*handle, uint32_t flags);

       During the data serving phase, this callback is used to fdatasync(2)
       the backing store, ie. to ensure	it has been completely written to a
       permanent medium.  If that is not possible then you can omit this
       callback.

       This function will not be called	directly by the	client if ".can_flush"
       returned	false; however,	it may still be	called by nbdkit if ".can_fua"
       returned	"NBDKIT_FUA_EMULATE".  The parameter "flags" exists in case of
       future NBD protocol extensions; at this time, it	will be	0 on input.

       If there	is an error, ".flush" should call "nbdkit_error" with an error
       message,	and "nbdkit_set_error" to record an appropriate	error (unless
       "errno" is sufficient), then return "-1".

   ".trim"
	int trim (void *handle,	uint32_t count,	uint64_t offset, uint32_t flags);

       During the data serving phase, this callback is used to "punch holes"
       in the backing store.  If that is not possible then you can omit	this
       callback.

       This function will not be called	if ".can_trim" returned	false.	The
       parameter "flags" may include "NBDKIT_FLAG_FUA" on input	based on the
       result of ".can_fua".

       If there	is an error, ".trim" should call "nbdkit_error"	with an	error
       message,	and "nbdkit_set_error" to record an appropriate	error (unless
       "errno" is sufficient), then return "-1".

   ".zero"
	int zero (void *handle,	uint32_t count,	uint64_t offset, uint32_t flags);

       During the data serving phase, this callback is used to write "count"
       bytes of	zeroes at "offset" in the backing store.

       This function will not be called	if ".can_zero" returned	false.	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".

       If "NBDKIT_FLAG_MAY_TRIM" is requested, the operation can punch a hole
       instead of writing actual zero bytes, but only if subsequent reads from
       the hole	read as	zeroes.

       If "NBDKIT_FLAG_FAST_ZERO" is requested,	the plugin must	decide up
       front if	the implementation is likely to	be faster than a corresponding
       ".pwrite"; if not, then it must immediately fail	with "ENOTSUP" or
       "EOPNOTSUPP" (whether by	"nbdkit_set_error" or "errno") and preferably
       without modifying the exported image.  It is acceptable to always fail
       a fast zero request (as a fast failure is better	than attempting	the
       write only to find out after the	fact that it was not fast after	all).
       Note that on Linux, support for "ioctl(BLKZEROOUT)" is insufficient for
       determining whether a zero request to a block device will be fast
       (because	the kernel will	perform	a slow fallback	when needed).

       The callback must write the whole "count" bytes if it can.  The NBD
       protocol	doesn't	allow partial writes (instead, these would be errors).
       If the whole "count" bytes was written successfully, the	callback
       should return 0 to indicate there was no	error.

       If there	is an error, ".zero" should call "nbdkit_error"	with an	error
       message,	and "nbdkit_set_error" to record an appropriate	error (unless
       "errno" is sufficient), then return "-1".

       If this callback	is omitted, or if it fails with	"ENOTSUP" or
       "EOPNOTSUPP" (whether by	"nbdkit_set_error" or "errno"),	then ".pwrite"
       will be used as an automatic fallback except when the client requested
       a fast zero.

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

       During the data serving phase, this callback is used to detect
       allocated, sparse and zeroed regions of the disk.

       This function will not be called	if ".can_extents" returned false.
       nbdkit's	default	behaviour in this case is to treat the whole virtual
       disk as if it was allocated.  Also, this	function will not be called by
       a client	that does not request structured replies (the --no-sr option
       of nbdkit can be	used to	test behavior when ".extents" is unavailable
       to the client).

       The callback should detect and return the list of extents overlapping
       the range "[offset...offset+count-1]".  The "extents" parameter points
       to an opaque object which the callback should fill in by	calling
       "nbdkit_add_extent".  See "Extents list"	below.

       If there	is an error, ".extents"	should call "nbdkit_error" with	an
       error message, and "nbdkit_set_error" to	record an appropriate error
       (unless "errno" is sufficient), then return "-1".

       Extents list

       The plugin "extents" callback is	passed an opaque pointer "struct
       nbdkit_extents *extents".  This structure represents a list of
       filesystem extents describing which areas of the	disk are allocated,
       which are sparse	(aholesa), and,	if supported, which are	zeroes.

       The "extents" callback should scan the disk starting at "offset"	and
       call "nbdkit_add_extent"	for each extent	found.

       Extents overlapping the range "[offset...offset+count-1]" should	be
       returned	if possible.  However nbdkit ignores extents < offset so the
       plugin may, if it is easier to implement, return	all extent information
       for the whole disk.  The	plugin may return extents beyond the end of
       the range.  It may also return extent information for less than the
       whole range, but	it must	return at least	one extent overlapping
       "offset".

       The extents must	be added in ascending order, and must be contiguous.

       The "flags" parameter of	the ".extents" callback	may contain the	flag
       "NBDKIT_FLAG_REQ_ONE".  This means that the client is only requesting
       information about the extent overlapping	"offset".  The plugin may
       ignore this flag, or as an optimization it may return just a single
       extent for "offset".

	int nbdkit_add_extent (struct nbdkit_extents *extents,
			       uint64_t	offset,	uint64_t length, uint32_t type);

       Add an extent covering "[offset...offset+length-1]" of one of the
       following four types:

       "type = 0"
	   A normal, allocated data extent.

       "type = NBDKIT_EXTENT_HOLE|NBDKIT_EXTENT_ZERO"
	   An unallocated extent, a.k.a. a aholea, which reads back as zeroes.
	   This	is the normal type of hole applicable to most disks.

       "type = NBDKIT_EXTENT_ZERO"
	   An allocated	extent which is	known to contain only zeroes.

       "type = NBDKIT_EXTENT_HOLE"
	   An unallocated extent (hole)	which does not read back as zeroes.
	   Note	this should only be used in specialized	circumstances such as
	   when	writing	a plugin for (or to emulate) certain SCSI drives which
	   do not guarantee that trimmed blocks	read back as zeroes.

       "nbdkit_add_extent" returns 0 on	success	or "-1"	on failure.  On
       failure "nbdkit_error" and/or "nbdkit_set_error"	has already been
       called.	"errno"	will be	set to a suitable value.

   ".cache"
	int cache (void	*handle, uint32_t count, uint64_t offset, uint32_t flags);

       During the data serving phase, this callback is used to give the	plugin
       a hint that the client intends to make further accesses to the given
       region of the export.  The nature of caching is not specified further
       by the NBD specification	(for example, a	server may place limits	on how
       much may	be cached at once, and there is	no way to control if writes to
       a cached	area have write-through	or write-back semantics).  In fact,
       the cache command can always fail and still be compliant, and success
       might not guarantee a performance gain.	If this	callback is omitted,
       then the	results	of ".can_cache"	determine whether nbdkit will reject
       cache requests, treat them as instant success, or emulate caching by
       calling ".pread"	over the same region and ignoring the results.

       This function will not be called	if ".can_cache"	did not	return
       "NBDKIT_CACHE_NATIVE".  The parameter "flags" exists in case of future
       NBD protocol extensions;	at this	time, it will be 0 on input. A plugin
       must fail this function if "flags" includes an unrecognized flag, as
       that may	indicate a requirement that the	plugin comply must with	a
       specific	caching	semantic.

       If there	is an error, ".cache" should call "nbdkit_error" with an error
       message,	and "nbdkit_set_error" to record an appropriate	error (unless
       "errno" is sufficient), then return "-1".

   ".errno_is_preserved"
       This field defaults to 0; if non-zero, nbdkit can reliably use the
       value of	"errno"	when a callback	reports	failure, rather	than the
       plugin having to	call "nbdkit_set_error".

SHUTDOWN
       When nbdkit receives certain signals it will shut down (see "SIGNALS"
       in nbdkit(1)).  The server will wait for	any currently running plugin
       callbacks to finish and also call the ".unload" callback	before
       unloading the plugin.

       Note that it's not guaranteed this can always happen (eg. the server
       might be	killed by "SIGKILL" or segfault).

   Requesting asynchronous shutdown
       Plugins and filters can call exit(3) in the configuration phase (before
       and including ".get_ready", but not in connected	callbacks).

       Once nbdkit has started serving connections, plugins and	filters	should
       not call	exit(3).  However they may instruct nbdkit to shut down	by
       calling "nbdkit_shutdown":

	void nbdkit_shutdown (void);

       This function requests an asynchronous shutdown and returns (note that
       it does not exit	the process immediately).  It ensures that the plugin
       and all filters are unloaded cleanly which may take some	time.  Further
       callbacks from nbdkit into the plugin or	filter may occur after you
       have called this.

PARSING	COMMAND	LINE PARAMETERS
   Parsing numbers
       There are several functions for parsing numbers.	 These all deal
       correctly with overflow,	out of range and parse errors, and you should
       use them	instead	of unsafe functions like sscanf(3), atoi(3) and
       similar.

	int nbdkit_parse_int (const char *what,	const char *str, int *r);
	int nbdkit_parse_unsigned (const char *what,
				   const char *str, unsigned *r);
	int nbdkit_parse_int8_t	(const char *what,
				 const char *str, int8_t *r);
	int nbdkit_parse_uint8_t (const	char *what,
				  const	char *str, uint8_t *r);
	int nbdkit_parse_int16_t (const	char *what,
				  const	char *str, int16_t *r);
	int nbdkit_parse_uint16_t (const char *what,
				   const char *str, uint16_t *r);
	int nbdkit_parse_int32_t (const	char *what,
				  const	char *str, int32_t *r);
	int nbdkit_parse_uint32_t (const char *what,
				   const char *str, uint32_t *r);
	int nbdkit_parse_int64_t (const	char *what,
				  const	char *str, int64_t *r);
	int nbdkit_parse_uint64_t (const char *what,
				   const char *str, uint64_t *r);

       Parse string "str" into an integer of various types.  These functions
       parse a decimal,	hexadecimal ("0x...") or octal ("0...")	number.

       On success the functions	return 0 and set *r to the parsed value
       (unless "*r == NULL" in which case the result is	discarded).  On	error,
       "nbdkit_error" is called	and the	functions return "-1".	On error *r is
       always unchanged.

       The "what" parameter is printed in error	messages to provide context.
       It should usually be a short descriptive	string of what you are trying
       to parse, eg:

	if (nbdkit_parse_int ("random seed", argv[1], &seed) ==	-1)
	  return -1;

       might print an error:

	random seed: could not parse number: "lalala"

   Parsing sizes
       Use the "nbdkit_parse_size" utility function to parse human-readable
       size strings such as "100M" into	the size in bytes.

	int64_t	nbdkit_parse_size (const char *str);

       "str" can be a string in	a number of common formats.  The function
       returns the size	in bytes.  If there was	an error, it returns "-1".

   Parsing booleans
       Use the "nbdkit_parse_bool" utility function to parse human-readable
       strings such as "on" into a boolean value.

	int nbdkit_parse_bool (const char *str);

       "str" can be a string containing	a case-insensitive form	of various
       common toggle values.  The function returns 0 or	1 if the parse was
       successful.  If there was an error, it returns "-1".

   Reading passwords
       The "nbdkit_read_password" utility function can be used to read
       passwords from config parameters:

	int nbdkit_read_password (const	char *value, char **password);

       For example:

	char *password = NULL;

	static int
	myplugin_config	(const char *key, const	char *value)
	{
	  ..
	  if (strcmp (key, "password") == 0) {
	    free (password);
	    if (nbdkit_read_password (value, &password)	== -1)
	      return -1;
	  }
	  ..
	}

       The "password" result string is allocated by malloc, and	so you may
       need to free it.

       This function recognizes	several	password formats.  A password may be
       used directly on	the command line, eg:

	nbdkit myplugin	password=mostsecret

       But more	securely this function can also	read a password	interactively:

	nbdkit myplugin	password=-

       or from a file:

	nbdkit myplugin	password=+/tmp/secret

       or from a file descriptor inherited by nbdkit:

	nbdkit myplugin	password=-99

       Notes on	reading	passwords

       If the password begins with a "-" or "+"	character then it must be
       passed in a file.

       "password=-" can	only be	used when stdin	is a terminal.

       "password=-FD" cannot be	used with stdin, stdout	or stderr (ie. "-0",
       "-1" or "-2").  The reason is that after	reading	the password the file
       descriptor is closed, which causes bad stuff to happen.

   Safely interacting with stdin and stdout
	int nbdkit_stdio_safe (void);

       The "nbdkit_stdio_safe" utility function	returns	1 if it	is safe	to
       interact	with stdin and stdout during the configuration phase, and 0
       otherwise.  This	is because when	the nbdkit -s option is	used the
       plugin must not directly	interact with stdin, because that would
       interfere with the client.

       The result of this function only	matters	in callbacks up	to
       ".config_complete".  Once nbdkit	reaches	".get_ready", the plugin
       should assume that nbdkit may have closed the original stdin and	stdout
       in order	to become a daemon.

       nbdkit-sh-plugin(3) uses	this function to determine whether it is safe
       to support "script=-" to	read a script from stdin.  Also	constructs
       like "password=-" (see "Reading passwords" above) are disabled when
       reading from stdio is not safe.

FILENAMES AND PATHS
       The server usually (not always) changes directory to "/"	before it
       starts serving connections.  This means that any	relative paths passed
       during configuration will not work when the server is running (example:
       "nbdkitA	plugin.soA disk.img").

       To avoid	problems, prepend relative paths with the current directory
       before storing them in the handle.  Or open files and store the file
       descriptor.

   "nbdkit_absolute_path"
	char *nbdkit_absolute_path (const char *filename);

       The utility function "nbdkit_absolute_path" converts any	path to	an
       absolute	path: if it is relative, then all this function	does is
       prepend the current working directory to	the path, with no extra
       checks.

       Note that this function works only when used in the ".config",
       ".config_complete" and ".get_ready" callbacks.

       If conversion was not possible, this calls "nbdkit_error" and returns
       "NULL".	Note that this function	does not check that the	file exists.

       The returned string must	be freed by the	caller.

   "nbdkit_realpath"
	char *nbdkit_realpath (const char *filename);

       The utility function "nbdkit_realpath" converts any path	to an absolute
       path, resolving symlinks.  Under	the hood it uses the "realpath"
       function, and thus it fails if the path does not	exist, or it is	not
       possible	to access to any of the	components of the path.

       Note that this function works only when used in the ".config",
       ".config_complete" and ".get_ready" callbacks.

       If the path resolution was not possible,	this calls "nbdkit_error" and
       returns "NULL".

       The returned string must	be freed by the	caller.

   umask
       All plugins will	see a umask(2) of 0022.

SLEEPING
       A plugin	that needs to sleep may	call sleep(2), nanosleep(2) and
       similar.	 However that can cause	nbdkit to delay	excessively when
       shutting	down (since it must wait for any plugin	or filter which	is
       sleeping).  To avoid this there is a special wrapper around nanosleep
       which plugins and filters should	use instead.

   "nbdkit_nanosleep"
	int nbdkit_nanosleep (unsigned sec, unsigned nsec);

       The utility function "nbdkit_nanosleep" suspends	the current thread,
       and returns 0 if	it slept at least as many seconds and nanoseconds as
       requested, or -1	after calling "nbdkit_error" if	there is no point in
       continuing the current command.	Attempts to sleep more than "INT_MAX"
       seconds are treated as an error.

EXPORT NAME
       If the client negotiated	an NBD export name with	nbdkit then plugins
       may read	this from any connected	callbacks.  Nbdkit's normal behaviour
       is to accept any	export name passed by the client, log it in debug
       output, but otherwise ignore it.	 By using "nbdkit_export_name" plugins
       may choose to filter by export name or serve different content.

   "nbdkit_export_name"
	const char *nbdkit_export_name (void);

       Return the optional NBD export name if one was negotiated with the
       current client (this uses thread-local magic so no parameter is
       required).  The returned	string is only valid while the client is
       connected, so if	you need to store it in	the plugin you must copy it.

       The export name is a free-form text string, it is not necessarily a
       path or filename	and it does not	need to	begin with a '/' character.
       The NBD protocol	describes the empty string ("")	as a representing a
       "default	export"	or to be used in cases where the export	name does not
       make sense.  The	export name is untrusted client	data, be cautious when
       parsing it.

       On error, "nbdkit_error"	is called and the call returns "NULL".

PEER NAME
       It is possible to get the address of the	client when you	are running in
       any connected callback.

   "nbdkit_peer_name"
	int nbdkit_peer_name (struct sockaddr *addr, socklen_t *addrlen);

       Return the peer (client)	address, if available.	The "addr" and
       "addrlen" parameters behave like	getpeername(2).	 In particular you
       must initialize "addrlen" with the size of the buffer pointed to	by
       "addr", and if "addr" is	not large enough then the address will be
       truncated.

       In some cases this is not available or the address returned will	be
       meaningless (eg.	if there is a proxy between the	client and nbdkit).
       This call uses thread-local magic so no parameter is required to
       specify the current connection.

       On success this returns 0.  On error, "nbdkit_error" is called and this
       call returns "-1".

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

	nbdkit -fv ./myplugin.so [key=value [key=value [...]]]

       To print	debugging information from within the plugin, 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
       The -v option switches general debugging	on or off, and this debugging
       should be used for messages which are useful for	all users of your
       plugin.

       In cases	where you want to enable specific extra	debugging to track
       down bugs in plugins or filters a mainly	for use	by the plugin/filter
       developers themselves a you can define Debug Flags.  These are global
       ints called "myplugin_debug_*":

	int myplugin_debug_foo;
	int myplugin_debug_bar;
	...
	if (myplugin_debug_foo)	{
	  nbdkit_debug ("lots of extra debugging about foo: ...");
	}

       Debug Flags can be controlled on	the command line using the -D (or
       --debug)	option:

	nbdkit -f -v -D	myplugin.foo=1 -D myplugin.bar=2 myplugin [...]

       Note "myplugin" is the name passed to ".name" in	the "struct
       nbdkit_plugin".

       You should only use this	feature	for debug settings.  For general
       settings	use ordinary plugin parameters.	 Debug Flags can only be C
       ints.  They are not supported by	non-C language plugins.

       For convenience '.' characters are replaced with	'_' characters in the
       variable	name, so both of these parameters:

	-D myplugin.foo_bar=1
	-D myplugin.foo.bar=1

       correspond to the plugin	variable "myplugin_debug_foo_bar".

COMPILING THE PLUGIN
       Plugins should be compiled as shared libraries.	There are various ways
       to achieve this,	but most Linux compilers support a -shared option to
       create the shared library directly, for example:

	gcc -fPIC -shared myplugin.c -o	myplugin.so

       Note that the shared library will have undefined	symbols	for functions
       that you	call like "nbdkit_parse_int" or	"nbdkit_error".	 These will be
       resolved	by the server binary when nbdkit dlopens the plugin.

   PKG-CONFIG/PKGCONF
       nbdkit provides a pkg-config/pkgconf file called	"nbdkit.pc" which
       should be installed on the correct path when the	nbdkit plugin
       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 plugins.

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

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

       You can also substitute the plugindir variable by doing:

	PKG_CHECK_VAR([NBDKIT_PLUGINDIR], [nbdkit], [plugindir])

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

       If nbdkit development headers are installed in a	non-standard location
       then you	may need to compile plugins using:

	gcc -fPIC -shared myplugin.c -o	myplugin.so \
	  `pkg-config nbdkit --cflags --libs`

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

	nbdkit /path/to/plugin.so [args]

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

	nbdkit name [args]

       The location of the $plugindir 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
       plugin directory	at compile time	by doing:

	pkg-config nbdkit --variable=plugindir

WRITING	PLUGINS	IN OTHER PROGRAMMING LANGUAGES
       You can also write nbdkit plugins in Go,	Lua, OCaml, Perl, Python,
       Ruby, Rust, shell script	or Tcl.	 Other programming languages may be
       offered in future.

       For more	information see: nbdkit-golang-plugin(3),
       nbdkit-lua-plugin(3), nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3),
       nbdkit-python-plugin(3),	nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3),
       nbdkit-sh-plugin(3), nbdkit-tcl-plugin(3) .

       Plugins written in scripting languages may also be installed in
       $plugindir.  These must be called "nbdkit-name-plugin" without any
       extension.  They	must be	executable, and	they must use the shebang
       header (see "Shebang scripts" in	nbdkit(1)).  For example a plugin
       written in Perl called "foo.pl" might be	installed like this:

	$ head -1 foo.pl
	#!/usr/sbin/nbdkit perl

	$ sudo install -m 0755 foo.pl $plugindir/nbdkit-foo-plugin

       and then	users will be able to run it like this:

	$ nbdkit foo [args ...]

SEE ALSO
       nbdkit(1), nbdkit-nozero-filter(3), nbdkit-filter(3).

       Standard	plugins	provided by nbdkit:

       nbdkit-curl-plugin(1), nbdkit-data-plugin(1), nbdkit-eval-plugin(1),
       nbdkit-example1-plugin(1), nbdkit-example2-plugin(1),
       nbdkit-example3-plugin(1), nbdkit-example4-plugin(1),
       nbdkit-ext2-plugin(1), nbdkit-file-plugin(1), nbdkit-floppy-plugin(1),
       nbdkit-full-plugin(1), nbdkit-guestfs-plugin(1),	nbdkit-gzip-plugin(1),
       nbdkit-info-plugin(1), nbdkit-iso-plugin(1), nbdkit-libvirt-plugin(1),
       nbdkit-linuxdisk-plugin(1), nbdkit-memory-plugin(1),
       nbdkit-nbd-plugin(1), nbdkit-null-plugin(1),
       nbdkit-partitioning-plugin(1), nbdkit-pattern-plugin(1),
       nbdkit-random-plugin(1),	nbdkit-split-plugin(1),	nbdkit-ssh-plugin(1),
       nbdkit-streaming-plugin(1), nbdkit-tar-plugin(1),
       nbdkit-tmpdisk-plugin(1), nbdkit-vddk-plugin(1),	nbdkit-zero-plugin(1)
       ; nbdkit-golang-plugin(3), nbdkit-lua-plugin(3),
       nbdkit-ocaml-plugin(3), nbdkit-perl-plugin(3), nbdkit-python-plugin(3),
       nbdkit-ruby-plugin(3), nbdkit-rust-plugin(3), nbdkit-sh-plugin(3),
       nbdkit-tcl-plugin(3) .

AUTHORS
       Eric Blake

       Richard W.M. Jones

       Pino Toscano

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-plugin(3)

NAME | SYNOPSIS | DESCRIPTION | WRITING AN NBDKIT PLUGIN | CALLBACKS | SHUTDOWN | PARSING COMMAND LINE PARAMETERS | FILENAMES AND PATHS | SLEEPING | EXPORT NAME | PEER NAME | DEBUGGING | COMPILING THE PLUGIN | INSTALLING THE PLUGIN | WRITING PLUGINS IN OTHER PROGRAMMING LANGUAGES | SEE ALSO | AUTHORS | COPYRIGHT | LICENSE

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

home | help