1libnbd(3) LIBNBD libnbd(3)
2
6 libnbd - network block device (NBD) client library in userspace
7
9 #include <libnbd.h>
10 struct nbd_handle *nbd;
12 char buf[512];
13 if ((nbd = nbd_create ()) == NULL ||
15 nbd_connect_tcp (nbd, "server.example.com", "nbd") == -1 ||
16 nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1)
17 fprintf (stderr, "%s\n", nbd_get_error ());
18 nbd_close (nbd);
19 exit (EXIT_FAILURE);
20 }
21 nbd_close (nbd);
22 cc prog.c -o prog -lnbd
24 or:
25 cc prog.c -o prog `pkg-config libnbd --cflags --libs`
26
28 Network Block Device (NBD) is a network protocol for accessing block
29 devices over the network. Block devices are hard disks and things that
30 behave like hard disks such as disk images and virtual machines.
31 Libnbd is a client library for the NBD protocol which can access most
33 of the features of NBD while being simple to use and powerful.
34 This manual page gives an overview of libnbd, using C as an example,
36 but the library is available from other programming languages.
37 nbd_create(3), nbd_pread(3), etc.
39 Each manual page covers one function from the C API in detail.
40 There is a full list in section "C API" below.
41 libnbd-ocaml(3)
43 Using the API from OCaml.
44 nbdsh(1)
46 Using the NBD shell (nbdsh) for command line and scripting.
47
49 To use the API at all you must first open a handle by calling
50 nbd_create(3) (or its equivalent in other languages):
51 struct nbd_handle *nbd;
53 nbd = nbd_create ();
55 This creates and returns a handle, which is associated with one
57 connection to an NBD server, initially not connected.
58 Each handle is a complex state machine which can be in states such as
60 created, connected to a remote server, handshaking, idle and ready to
61 issue commands, or busy sending or receiving commands.
62 There are two levels of API available. A simple high level synchronous
64 API lets you give the handle high level instructions like “connect to
65 the server”, “read a block”, “write a block”, etc. Each of these
66 functions will run to completion, blocking the current thread before
67 returning. A more complicated low level non-blocking asynchronous API
68 is also available where you can integrate with poll(2) or another main
69 loop.
70 You can freely mix the two APIs on the same handle. You can also call
72 APIs on a single handle from multiple threads. Single API calls on the
73 handle are atomic — they either take a lock on the handle while they
74 run or are careful to access handle fields atomically.
75 Libnbd does not create its own threads.
77
79 This is the simplest way to use the API, with the possible drawback
80 that each libnbd function blocks until it is finished.
81 Create a handle and connect to the server:
83 struct nbd_handle *nbd;
85 nbd = nbd_create ();
87 if (!nbd) {
88 fprintf (stderr, "%s\n", nbd_get_error ());
89 nbd_close (nbd);
90 exit (EXIT_FAILURE);
91 }
92 if (nbd_connect_tcp (nbd, "server.example.com", "nbd") == -1) {
93 fprintf (stderr, "%s\n", nbd_get_error ());
94 nbd_close (nbd);
95 exit (EXIT_FAILURE);
96 }
97 Read the first sector (512 bytes) from the NBD export:
99 char buf[512];
101 if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) {
103 fprintf (stderr, "%s\n", nbd_get_error ());
104 nbd_close (nbd);
105 exit (EXIT_FAILURE);
106 }
107 Close the handle:
109 nbd_close (nbd);
111 You can call the high level API from multiple threads, but each libnbd
113 API call takes a lock on the handle and so commands will not run in
114 parallel.
115
117 The low level API is useful if you want to use libnbd in non-blocking
118 code; or if you want to issue commands in parallel from multiple
119 threads; or if you need more control especially over having multiple
120 commands in-flight on a single connection.
121 To use the low level API you will need to integrate with poll(2) or
123 another “main loop” such as the GLib main event loop.
124 Issuing asynchronous commands
126 Use the "nbd_aio_*" variants to issue commands asynchronously (without
127 waiting for the command to complete before returning). For example the
128 asynchronous variant of nbd_pread(3) is:
129 int64_t cookie;
131 cookie = nbd_aio_pread (nbd, buf, sizeof buf,
133 NBD_NULL_COMPLETION, 0);
134 if (cookie == -1) {
135 fprintf (stderr, "%s\n", nbd_get_error ());
136 nbd_close (nbd);
137 exit (EXIT_FAILURE);
138 }
139 There are several things to note here:
141 · This only starts the command. The command is still in flight when
143 the call returns.
144 · A buffer ("buf") has been assigned to collect the result of the
146 read, but it is not guaranteed to be filled with data until the
147 command has completed (see examples below). The buffer must not be
148 freed until the command has finished running.
149 · You can issue multiple commands on the same handle at the same
151 time.
152 · A cookie is returned which identifies this command in subsequent
154 calls. The cookie is unique (per libnbd handle) and ≥ 1.
155 · You may register a function which is called when the command
157 completes, see "Completion callbacks" below. In this case we have
158 specified a null completion callback.
159 Socket and direction
161 Each libnbd handle has an associated socket (once it has started
162 connecting). You can read the file descriptor of the socket using:
163 int fd = nbd_aio_get_fd (nbd);
165 The socket is non-blocking. Between calls into libnbd it is in the
167 "would block" condition. You can find out if libnbd is expecting to
168 read or write from the socket next by calling:
169 int dir = nbd_aio_get_direction (nbd);
171 which returns one of "LIBNBD_AIO_DIRECTION_READ",
173 "LIBNBD_AIO_DIRECTION_WRITE" or "LIBNBD_AIO_DIRECTION_BOTH" (=
174 "READ|WRITE"). And so to set up the next call to poll(2) or other main
175 loop you must translate this to "POLLIN", "POLLOUT" or "POLLIN|POLLOUT"
176 (or whatever mechanism your main loop uses).
177 Notifying libnbd when an event happens
179 When you detect (eg. using poll(2)) that a read or write event has
180 happened on the socket, you must then tell libnbd about it. You have
181 to check the direction again (since it may have been changed by another
182 thread), and notify libnbd:
183 int r = 0;
185 dir = nbd_aio_get_direction (nbd);
187 if ((dir & LIBNBD_AIO_DIRECTION_READ) &&
189 a_read_event_occurred ())
190 r = nbd_aio_notify_read (nbd);
191 else if ((dir & LIBNBD_AIO_DIRECTION_WRITE) &&
192 a_write_event_occurred ())
193 r = nbd_aio_notify_write (nbd);
194 if (r == -1) {
196 fprintf (stderr, "%s\n", nbd_get_error ());
197 // ...
198 }
199 The notify calls move the state machine along, reading and writing from
201 the socket possibly multiple times, until the socket would block again,
202 at which point they return control to the caller.
203 Simple implementation with nbd_poll(3)
205 In fact if you want to use poll(2) on a single handle, a simple
206 implementation has already been written called nbd_poll(3). It is also
207 useful to examine how this is implemented (lib/poll.c in the libnbd
208 source code) because that will tell you how to integrate libnbd with
209 more complex main loops.
210 Some examples of using nbd_poll(3) follow.
212 As with the high level API, it all starts by creating a handle:
214 struct nbd_handle *nbd;
216 nbd = nbd_create ();
218 if (nbd == NULL) {
219 fprintf (stderr, "%s\n", nbd_get_error ());
220 nbd_close (nbd);
221 exit (EXIT_FAILURE);
222 }
223 To connect to the server asynchronously, we start the connection using
225 nbd_aio_connect(3) and then enter our main loop to check for events
226 until the connection becomes ready:
227 int fd;
229 struct sockaddr_un addr;
230 socklen_t len;
231 /* some code to set up addr,
233 then ... */
234 if (nbd_aio_connect (nbd, &addr, len) == -1) {
235 fprintf (stderr, "%s\n", nbd_get_error ());
236 nbd_close (nbd);
237 exit (EXIT_FAILURE);
238 }
239 while (! nbd_aio_is_ready (nbd)) {
240 if (nbd_poll (nbd, -1) == -1) {
241 fprintf (stderr, "%s\n", nbd_get_error ());
242 nbd_close (nbd);
243 exit (EXIT_FAILURE);
244 }
245 }
246 To read data asynchronously, start an asynchronous read command, which
248 returns a 64 bit command cookie, and enter the main loop until the
249 command has completed:
250 int64_t cookie;
252 char buf[512];
253 cookie = nbd_aio_pread (nbd, buf, sizeof buf, offset,
255 NBD_NULL_COMPLETION, 0);
256 if (cookie == -1) {
257 fprintf (stderr, "%s\n", nbd_get_error ());
258 nbd_close (nbd);
259 exit (EXIT_FAILURE);
260 }
261 while (! nbd_aio_command_completed (nbd, cookie)) {
262 if (nbd_poll (nbd, -1) == -1) {
263 fprintf (stderr, "%s\n", nbd_get_error ());
264 nbd_close (nbd);
265 exit (EXIT_FAILURE);
266 }
267 }
268 For almost all high level synchronous calls (eg. nbd_pread(3)) there is
270 a low level asynchronous equivalent (eg. nbd_aio_pread(3)) for starting
271 a command.
272 glib2 integration
274 See
275 https://github.com/libguestfs/libnbd/blob/master/examples/glib-main-loop.c
276
278 When any API call returns an error ("-1" or "NULL" depending on the
279 API), an error message and sometimes an errno value are available. You
280 can retrieve the error message and/or errno of the most recently failed
281 call using nbd_get_error(3) and nbd_get_errno(3). For example:
282 if (nbd_connect_tcp (nbd, "remote", "nbd") == -1) {
284 fprintf (stderr,
285 "failed to connect to remote server: %s (errno = %d)\n",
286 nbd_get_error (), nbd_get_errno ());
287 }
288 These functions use thread-local storage to return the most recent
290 error in the current thread. This is why you don't need to pass the
291 handle to these calls. They even work if nbd_create(3) returns "NULL"
292 when there is no handle at all.
293 For this reason you cannot call them from a different thread. You
295 should call them immediately after the failed API call, from the same
296 thread. Furthermore the error string returned by nbd_get_error(3) is
297 only valid until the next libnbd API call in the current thread, so if
298 you need to keep the string you must copy it (eg. using strdup(3)).
299 Errno
301 For some errors, a system call error number (see errno(3)) is
302 available. You can find the error number by calling nbd_get_errno(3).
303 It works the same way as nbd_get_error(3) with respect to threads.
304 Even when a call returns an error, nbd_get_errno(3) might return 0.
306 This does not mean there was no error. It means no additional errno
307 information is available for this error.
308 The error number is often the raw error returned by a system call that
310 failed.
311 It can also be used to indicate special conditions. The most common
313 cases are:
314 "EINVAL"
316 Invalid parameters or state for the current libnbd call.
317 "ENOTSUP"
319 The libnbd call is not available in this build of libnbd (eg. when
320 using a TLS API if the library was compiled without TLS support).
321 "ENOMEM"
323 The library ran out of memory while performing some operation.
324 "ERANGE"
326 A request is too large, for example if you try to read too many
327 bytes in a single nbd_pread(3) call.
328
330 Libnbd can print lots of debugging messages, useful if you have a
331 problem with the library. Either enable debugging after creating the
332 handle:
333 nbd = nbd_create ();
335 nbd_set_debug (nbd, true);
336 or set the "LIBNBD_DEBUG=1" environment variable which will enable
338 debugging by default on all new handles.
339 Debugging messages are sent to stderr by default, but you can redirect
341 them to a logging system using nbd_set_debug_callback(3).
342
344 There are several ways to connect to NBD servers, and you can even run
345 a server from libnbd. Normally you would connect to a server which is
346 already running, over a local Unix domain socket or a remote TCP
347 connection. The high level API calls are:
348 nbd_connect_unix (nbd, "socket");
350 nbd_connect_tcp (nbd, "localhost", "nbd");
351 For nbd_connect_tcp(3) the third parameter is the port name or number,
353 which can either be a name from /etc/services or the port number as a
354 string (eg. "10809").
355 Connecting to an NBD URI
357 libnbd supports the NBD URI specification. The URIs that libnbd
358 currently supports is documented in nbd_connect_uri(3).
359 You can connect to a URI as in these examples (using the high level
361 API):
362 nbd_connect_uri (nbd, "nbd://example.com/");
364 nbd_connect_uri (nbd, "nbds+unix:///export?socket=/tmp/nbd.sock");
366 This feature is implemented by calling other libnbd APIs to set up the
368 export name, TLS parameters, and finally connect over a Unix domain
369 socket or TCP.
370 URI support is an optional feature of the library, requiring libxml2 at
372 compile time. The nbd_connect_uri(3) and nbd_aio_connect_uri(3) calls
373 will raise an error (with nbd_get_errno(3) returning "ENOTSUP") if it
374 was not built with this feature, and you can also test for it
375 explicitly using nbd_supports_uri(3).
376 Connecting to a subprocess
378 Some NBD servers — notably nbdkit(1) with the -s parameter, and
379 nbd-server(1) with the port parameter set to 0 — can also accept a
380 single NBD connection on stdin/stdout. You can run these servers as a
381 subprocess of your main program using nbd_connect_command(3). This
382 example creates a 1G writable RAM disk:
383 char *argv[] = { "nbdkit", "-s", "--exit-with-parent",
385 "memory", "1G", NULL };
386 nbd_connect_command (nbd, argv);
387 When the handle is closed the nbdkit subprocess is killed, which in
389 this case means the RAM disk is discarded, so this is useful for
390 testing.
391 Connecting to a subprocess using systemd socket activation
393 Some NBD servers — notably nbdkit(1) and qemu-nbd(1) — support systemd
394 socket activation allowing libnbd to pass a socket to the subprocess.
395 This works very similarly to nbd_connect_command(3) described above,
396 but you must use nbd_connect_systemd_socket_activation(3) instead.
397
399 It is possible for NBD servers to serve different content on different
400 “exports”. For this you must pass the right export name to the server.
401 Call this API before connecting:
402 nbd_set_export_name (nbd, "export");
404 Note that there are some servers (like nbdkit(1) ≤ 1.14) which ignore
406 this, and other servers (like qemu-nbd(8)) which require it to be set
407 correctly but cannot serve different content.
408 Flag calls
410 After connecting the server will send back a set of flags describing
411 the export, such as whether it is writable and if it can support flush
412 to permanent storage. These flags can be accessed from libnbd using
413 APIs such as:
414 int is_read_only = nbd_is_read_only (nbd);
416 int can_flush = nbd_can_flush (nbd);
417 Flag calls are: nbd_can_cache(3), nbd_can_df(3), nbd_can_fast_zero(3),
419 nbd_can_flush(3), nbd_can_fua(3), nbd_can_meta_context(3),
420 nbd_can_multi_conn(3), nbd_can_trim(3), nbd_can_zero(3),
421 nbd_is_read_only(3), nbd_is_rotational(3).
422 Size of the export
424 To get the size of the export in bytes, use nbd_get_size(3):
425 int64_t size = nbd_get_size (nbd);
427
429 You can read and write data from the NBD server using nbd_pread(3) and
430 nbd_pwrite(3) or their asynchronous equivalents.
431 Some servers also support:
433 trim/discard
435 If nbd_can_trim(3) returns true, nbd_trim(3) can be used to “punch
436 holes” in the backing storage of the disk on the server. Normally
437 (although not in every case) the holes read back as zeroes but take
438 up no space.
439 zeroing
441 If nbd_can_zero(3) returns true, nbd_zero(3) can be used to
442 efficiently zero parts of the disk without having to send large
443 amounts of zero bytes over the network (as would be necessary if
444 using nbd_pwrite(3)).
445 This is slightly different from trimming because the backing
447 storage is still allocated. For some storage types this can make
448 future writes more efficient and/or less likely to fail because of
449 out of space errors.
450 flushing
452 Some servers can commit data to permanent storage and tell you that
453 this has happened reliably. There are two export flags associated
454 with this: nbd_can_flush(3) and nbd_can_fua(3).
455 The nbd_flush(3) call (available if nbd_can_flush(3) returns true)
457 flushes all pending writes to disk and does not complete until that
458 operation has finished. It is similar to using sync(2) on POSIX
459 systems.
460 A more efficient way to achieve this is to set the flag
462 "LIBNBD_CMD_FLAG_FUA" on write-like calls (like write, trim and
463 zero). This flag means the call will not complete until committed
464 to permanent storage, but it does not involve flushing the entire
465 disk.
466 prefetching
468 Some servers can prefetch data, making subsequent reads faster.
469 The nbd_cache(3) call (available if nbd_can_cache(3) returns true)
470 is used to prefetch.
471 block status
473 Some servers are able to provide information about the various
474 extents within the image, via the notion of one or more meta
475 contexts. The most common meta context is "base:allocation"
476 (available in libnbd.h as "LIBNBD_CONTEXT_BASE_ALLOCATION"), which
477 can be used to learn which portions of a file are allocated or read
478 as zero. Other contexts may be available; for example, qemu-nbd(8)
479 can expose a meta context "qemu:dirty-bitmap:NAME" for tracking
480 which portions of a file are tracked by a qcow2 dirty bitmap.
481 In order to utilize block status, the client must call
483 nbd_add_meta_context(3) prior to connecting, for each meta context
484 in which it is interested, then check nbd_can_meta_context(3) after
485 connection to see which contexts the server actually supports. If
486 a context is supported, the client can then use nbd_block_status(3)
487 with a callback function that will receive an array of 32-bit
488 integer pairs describing consecutive extents within a context. In
489 each pair, the first integer is the length of the extent, the
490 second is a bitmask description of that extent (for the
491 "base:allocation" context, the bitmask may include
492 "LIBNBD_STATE_HOLE" for unallocated portions of the file, and/or
493 "LIBNBD_STATE_ZERO" for portions of the file known to read as
494 zero).
495 There is a full example of requesting meta context and using block
497 status available at
498 https://github.com/libguestfs/libnbd/blob/master/interop/dirty-bitmap.c
499
501 Issuing multiple in-flight requests
502 NBD servers which properly implement the specification can handle
503 multiple requests in flight over the same connection at the same time.
504 Libnbd supports this when using the low level API.
505 To use it you simply issue more requests as needed (eg. using calls
507 like nbd_aio_pread(3), nbd_aio_pwrite(3)) without waiting for previous
508 commands to complete. You need to be careful that requests in flight
509 do not overlap with disk offsets of other write-like commands in flight
510 — an overlapping read may see indeterminate data, and an overlapping
511 write may even cause disk corruption where the resulting disk contents
512 do not match either of the two writes.
513 Each request is identified by a unique 64 bit cookie (assigned by
515 libnbd), allowing libnbd and callers to match replies to requests.
516 Replies may arrive out of order.
517 Although in theory you can have an indefinite number of requests in
519 flight at the same time, in practice it's a good idea to limit them to
520 some number. Libnbd will queue commands in the handle even if it
521 cannot write them to the server, so this limit is largely to prevent a
522 backlog of commands from consuming too much memory. It is suggested to
523 start with a limit of 64 requests in flight (per NBD connection), and
524 measure how adjusting the limit up and down affects performance for
525 your local configuration.
526 There is a full example using multiple in-flight requests available at
528 https://github.com/libguestfs/libnbd/blob/master/examples/threaded-reads-and-writes.c
529 Multi-conn
531 Some NBD servers advertise “multi-conn” which means that it is safe to
532 make multiple connections to the server and load-balance commands
533 across all of the connections.
534 To do this you should open a single connection first and test for this
536 feature using nbd_can_multi_conn(3). Without error handling it would
537 look like this:
538 struct nbd_handle *nbd[4];
540 size_t i;
541 bool supports_multi_conn;
542 nbd[0] = nbd_create ();
544 nbd_connect_tcp (nbd[0], "server", "10809");
545 supports_multi_conn = nbd_can_multi_conn (nbd[0]) > 0;
546 If multi-conn is supported then you can open further connections:
548 if (supports_multi_conn) {
550 for (i = 1; i <= 3; ++i) {
551 nbd[i] = nbd_create ();
552 nbd_connect_tcp (nbd[i], "server", "10809");
553 }
554 }
555 If you are issuing multiple in-flight requests (see above) and limiting
557 the number, then the limit should be applied to each individual NBD
558 connection.
559
561 The NBD protocol and libnbd supports TLS (sometimes incorrectly called
562 “SSL”) for encryption of the data stream and authentication of clients
563 and servers. Libnbd defaults to TLS disabled for maximum
564 interoperability. To enable it on a handle you must call
565 nbd_set_tls(3) before connecting.
566 To allow TLS, but fall back to unencrypted:
568 nbd_set_tls (nbd, LIBNBD_TLS_ALLOW);
570 Use nbd_get_tls_negotiated(3) to find out if TLS negotiation was
572 successful. Avoid "LIBNBD_TLS_ALLOW" if man-in-the-middle attacks are
573 a concern.
574 The most secure mode is to require TLS and fail to connect if the
576 server does not support it:
577 nbd_set_tls (nbd, LIBNBD_TLS_REQUIRE);
579 It may also be necessary to verify that the server’s identity is
581 correct. For some servers it may be necessary to verify to the server
582 that the client is permitted to connect. This can be done using either
583 X.509 certificates, or TLS Pre-Shared Keys (PSK). Certificates are
584 more secure. PSK is far more convenient, but you must have an existing
585 secure channel to distribute the keys.
586 Setting up X.509 using system certificate authorities (CAs)
588 This is the default if you don’t call any other "nbd_set_tls_*"
589 functions. In this case the server must have a public (eg. HTTPS)
590 certificate which can be verified against the CAs registered on your
591 system (eg. under /etc/pki).
592 To disable server name verification — which opens you up to a potential
594 Man-In-The-Middle (MITM) attack — use:
595 nbd_set_tls_verify_peer (nbd, false);
597 Setting up an X.509 certificate authority (CA)
599 You can set up your own CA and register clients and servers with it,
600 issuing client and server certificates which will reliably authenticate
601 your clients and servers to each other.
602 Doing this is described in detail in the nbdkit-tls(1) manual. The
604 only differences for libnbd are:
605 · Non-root certificates must be placed in "$HOME/.pki/libnbd/" or
607 "$HOME/.config/pki/libnbd/"
608 · Libnbd reads client-cert.pem and client-key.pem (instead of
610 server-cert.pem and server-key.pem).
611 Once you have set up the directory containing the certificates, call:
613 nbd_set_tls_certificates (nbd, "/path/to/directory");
615 Setting up Pre-Shared Keys (PSK)
617 TLS Pre-Shared Keys are a much more convenient method of setting up
618 TLS, and more appropriate for NBD, but you should have an existing
619 secure method available to distribute the keys. They are therefore
620 ideal if you want to set up an NBD service as an adjunct to an existing
621 secure REST API.
622 Use psktool(1) to create a file of "username:key" pairs:
624 psktool -u username -p keys.psk
626 and pass this path to libnbd:
628 nbd_set_tls_psk_file (nbd, "keys.psk");
630 If necessary you may need to set the client username (otherwise libnbd
632 will use your login name):
633 nbd_set_tls_username (nbd, "username");
635
637 Some libnbd calls take callbacks (eg. nbd_set_debug_callback(3),
638 nbd_aio_pread(3)). Libnbd can call these functions while processing.
639 In the C API these libnbd calls take a structure which contains the
641 function pointer and an optional opaque "void *user_data" pointer:
642 nbd_aio_pread (nbd, buf, sizeof buf, offset,
644 (nbd_completion_callback) { .callback = my_fn,
645 .user_data = my_data },
646 0);
647 For optional callbacks, if you don't want the callback, either set
649 ".callback" to "NULL" or use the equivalent macros (such as
650 "NBD_NULL_COMPLETION") defined in "libnbd.h":
651 nbd_aio_pread (nbd, buf, sizeof buf, offset,
653 NBD_NULL_COMPLETION, 0);
654 From other languages the structure and opaque pointer are not needed
656 because you can use closures to achieve the same effect.
657 Callback lifetimes
659 You can associate an optional free function with callbacks. Libnbd
660 will call this function when the callback will not be called again by
661 libnbd.
662 This can be used to free associated "user_data". For example:
664 void *my_data = malloc (...);
666 nbd_aio_pread_structured (nbd, buf, sizeof buf, offset,
668 (nbd_chunk_callback) { .callback = my_fn,
669 .user_data = my_data,
670 .free = free },
671 NBD_NULL_CALLBACK(completion),
672 0);
673 will call free(3) on "my_data" after the last time that the
675 "chunk.callback = my_fn" function is called.
676 The free function is only accessible in the C API as it is not needed
678 in garbage collected programming languages.
679 Callbacks with ".callback=NULL" and ".free!=NULL"
681 It is possible to register a callback like this:
682 ...
684 (nbd_completion_callback) { .callback = NULL,
685 .user_data = my_data,
686 .free = free },
687 ...
688 The meaning of this is that the callback is never called, but the free
690 function is still called after the last time the callback would have
691 been called. This is useful for applying generic freeing actions when
692 asynchronous commands are retired.
693 Callbacks and locking
695 The callbacks are invoked at a point where the libnbd lock is held; as
696 such, it is unsafe for the callback to call any "nbd_*" APIs on the
697 same nbd object, as it would cause deadlock.
698 Completion callbacks
700 All of the low-level commands have a completion callback variant that
701 registers a callback function used right before the command is marked
702 complete.
703 When the completion callback returns 1, the command is automatically
705 retired (there is no need to call nbd_aio_command_completed(3)); for
706 any other return value, the command still needs to be retired.
707 Callbacks with "int *error" parameter
709 Some of the high-level commands (nbd_pread_structured(3),
710 nbd_block_status(3)) involve the use of a callback function invoked by
711 the state machine at appropriate points in the server's reply before
712 the overall command is complete. These callback functions, along with
713 all of the completion callbacks, include a parameter "error" containing
714 the value of any error detected so far; if the callback function fails,
715 it should assign back into "error" and return "-1" to change the
716 resulting error of the overall command. Assignments into "error" are
717 ignored for any other return value; similarly, assigning 0 into "error"
718 does not have an effect.
719
721 "HOME"
722 Used in some situations to find TLS certificates. See
723 nbd_set_tls_certificates(3).
724 "LIBNBD_DEBUG"
726 If this is set to the exact string 1 when the handle is created
727 then debugging is enabled. See "DEBUGGING MESSAGES" above.
728 "LOGNAME"
730 The default TLS username. See nbd_set_tls_username(3).
731
733 C API
734 nbd_add_meta_context(3), nbd_aio_block_status(3), nbd_aio_cache(3),
735 nbd_aio_command_completed(3), nbd_aio_connect(3),
736 nbd_aio_connect_command(3), nbd_aio_connect_socket(3),
737 nbd_aio_connect_systemd_socket_activation(3), nbd_aio_connect_tcp(3),
738 nbd_aio_connect_unix(3), nbd_aio_connect_uri(3),
739 nbd_aio_connect_vsock(3), nbd_aio_disconnect(3), nbd_aio_flush(3),
740 nbd_aio_get_direction(3), nbd_aio_get_fd(3), nbd_aio_in_flight(3),
741 nbd_aio_is_closed(3), nbd_aio_is_connecting(3), nbd_aio_is_created(3),
742 nbd_aio_is_dead(3), nbd_aio_is_processing(3), nbd_aio_is_ready(3),
743 nbd_aio_notify_read(3), nbd_aio_notify_write(3),
744 nbd_aio_peek_command_completed(3), nbd_aio_pread(3),
745 nbd_aio_pread_structured(3), nbd_aio_pwrite(3), nbd_aio_trim(3),
746 nbd_aio_zero(3), nbd_block_status(3), nbd_cache(3), nbd_can_cache(3),
747 nbd_can_df(3), nbd_can_fast_zero(3), nbd_can_flush(3), nbd_can_fua(3),
748 nbd_can_meta_context(3), nbd_can_multi_conn(3), nbd_can_trim(3),
749 nbd_can_zero(3), nbd_clear_debug_callback(3), nbd_close(3),
750 nbd_connect_command(3), nbd_connect_socket(3),
751 nbd_connect_systemd_socket_activation(3), nbd_connect_tcp(3),
752 nbd_connect_unix(3), nbd_connect_uri(3), nbd_connect_vsock(3),
753 nbd_connection_state(3), nbd_create(3), nbd_flush(3), nbd_get_debug(3),
754 nbd_get_errno(3), nbd_get_error(3), nbd_get_export_name(3),
755 nbd_get_handle_name(3), nbd_get_handshake_flags(3),
756 nbd_get_package_name(3), nbd_get_protocol(3),
757 nbd_get_request_structured_replies(3), nbd_get_size(3),
758 nbd_get_structured_replies_negotiated(3), nbd_get_tls(3),
759 nbd_get_tls_negotiated(3), nbd_get_tls_username(3),
760 nbd_get_tls_verify_peer(3), nbd_get_version(3), nbd_is_read_only(3),
761 nbd_is_rotational(3), nbd_kill_subprocess(3), nbd_poll(3),
762 nbd_pread(3), nbd_pread_structured(3), nbd_pwrite(3), nbd_set_debug(3),
763 nbd_set_debug_callback(3), nbd_set_export_name(3),
764 nbd_set_handle_name(3), nbd_set_handshake_flags(3),
765 nbd_set_request_structured_replies(3), nbd_set_tls(3),
766 nbd_set_tls_certificates(3), nbd_set_tls_psk_file(3),
767 nbd_set_tls_username(3), nbd_set_tls_verify_peer(3),
768 nbd_set_uri_allow_local_file(3), nbd_set_uri_allow_tls(3),
769 nbd_set_uri_allow_transports(3), nbd_shutdown(3), nbd_supports_tls(3),
770 nbd_supports_uri(3), nbd_trim(3), nbd_zero(3).
771 Servers
773 nbdkit(1), nbd-server(1), qemu-nbd(8).
774 Encryption tools
776 certtool(1), nbdkit-tls(1), psktool(1).
777 Standards
779 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
780 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md.
781 Other
783 libnbd-release-notes-1.2(1), libnbd-security(3), nbdfuse(1), nbdsh(1),
784 qemu(1).
785
787 Eric Blake
788 Richard W.M. Jones
790
792 Copyright (C) 2019 Red Hat Inc.
793
795 This library is free software; you can redistribute it and/or modify it
796 under the terms of the GNU Lesser General Public License as published
797 by the Free Software Foundation; either version 2 of the License, or
798 (at your option) any later version.
799 This library is distributed in the hope that it will be useful, but
801 WITHOUT ANY WARRANTY; without even the implied warranty of
802 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
803 Lesser General Public License for more details.
804 You should have received a copy of the GNU Lesser General Public
806 License along with this library; if not, write to the Free Software
807 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
808 02110-1301 USA
809libnbd-1.2.1 2019-11-14 libnbd(3)