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 libnbd-golang(3)
46 Using the API from Go.
47 nbdsh(1)
49 Using the NBD shell (nbdsh) for command line and scripting.
50
52 To use the API at all you must first open a handle by calling
53 nbd_create(3) (or its equivalent in other languages):
54 struct nbd_handle *nbd;
56 nbd = nbd_create ();
58 This creates and returns a handle, which is associated with one
60 connection to an NBD server, initially not connected.
61 Each handle is a complex state machine which can be in states such as
63 created, connected to a remote server, handshaking, idle and ready to
64 issue commands, or busy sending or receiving commands.
65 There are two levels of API available. A simple high level synchronous
67 API lets you give the handle high level instructions like “connect to
68 the server”, “read a block”, “write a block”, etc. Each of these
69 functions will run to completion, blocking the current thread before
70 returning. A more complicated low level non-blocking asynchronous API
71 is also available where you can integrate with poll(2) or another main
72 loop.
73 You can freely mix the two APIs on the same handle. You can also call
75 APIs on a single handle from multiple threads. Single API calls on the
76 handle are atomic — they either take a lock on the handle while they
77 run or are careful to access handle fields atomically.
78 Libnbd does not create its own threads.
80
82 This is the simplest way to use the API, with the possible drawback
83 that each libnbd function blocks until it is finished.
84 Create a handle and connect to the server:
86 struct nbd_handle *nbd;
88 nbd = nbd_create ();
90 if (!nbd) {
91 fprintf (stderr, "%s\n", nbd_get_error ());
92 nbd_close (nbd);
93 exit (EXIT_FAILURE);
94 }
95 if (nbd_connect_tcp (nbd, "server.example.com", "nbd") == -1) {
96 fprintf (stderr, "%s\n", nbd_get_error ());
97 nbd_close (nbd);
98 exit (EXIT_FAILURE);
99 }
100 Read the first sector (512 bytes) from the NBD export:
102 char buf[512];
104 if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) {
106 fprintf (stderr, "%s\n", nbd_get_error ());
107 nbd_close (nbd);
108 exit (EXIT_FAILURE);
109 }
110 Close the handle:
112 nbd_close (nbd);
114 You can call the high level API from multiple threads, but each libnbd
116 API call takes a lock on the handle and so commands will not run in
117 parallel.
118
120 The low level API is useful if you want to use libnbd in non-blocking
121 code; or if you want to issue commands in parallel from multiple
122 threads; or if you need more control especially over having multiple
123 commands in-flight on a single connection.
124 To use the low level API you will need to integrate with poll(2) or
126 another “main loop” such as the GLib main event loop.
127 Issuing asynchronous commands
129 Use the "nbd_aio_*" variants to issue commands asynchronously (without
130 waiting for the command to complete before returning). For example the
131 asynchronous variant of nbd_pread(3) is:
132 int64_t cookie;
134 cookie = nbd_aio_pread (nbd, buf, sizeof buf,
136 NBD_NULL_COMPLETION, 0);
137 if (cookie == -1) {
138 fprintf (stderr, "%s\n", nbd_get_error ());
139 nbd_close (nbd);
140 exit (EXIT_FAILURE);
141 }
142 There are several things to note here:
144 · This only starts the command. The command is still in flight when
146 the call returns.
147 · A buffer ("buf") has been assigned to collect the result of the
149 read, but it is not guaranteed to be filled with data until the
150 command has completed (see examples below). The buffer must not be
151 freed until the command has finished running.
152 · You can issue multiple commands on the same handle at the same
154 time.
155 · A cookie is returned which identifies this command in subsequent
157 calls. The cookie is unique (per libnbd handle) and ≥ 1.
158 · You may register a function which is called when the command
160 completes, see "Completion callbacks" below. In this case we have
161 specified a null completion callback.
162 Socket and direction
164 Each libnbd handle has an associated socket (once it has started
165 connecting). You can read the file descriptor of the socket using:
166 int fd = nbd_aio_get_fd (nbd);
168 The socket is non-blocking. Between calls into libnbd it is in the
170 "would block" condition. You can find out if libnbd is expecting to
171 read or write from the socket next by calling:
172 int dir = nbd_aio_get_direction (nbd);
174 which returns one of "LIBNBD_AIO_DIRECTION_READ",
176 "LIBNBD_AIO_DIRECTION_WRITE" or "LIBNBD_AIO_DIRECTION_BOTH" (=
177 "READ|WRITE"). And so to set up the next call to poll(2) or other main
178 loop you must translate this to "POLLIN", "POLLOUT" or "POLLIN|POLLOUT"
179 (or whatever mechanism your main loop uses).
180 Notifying libnbd when an event happens
182 When you detect (eg. using poll(2)) that a read or write event has
183 happened on the socket, you must then tell libnbd about it. You have
184 to check the direction again (since it may have been changed by another
185 thread), and notify libnbd:
186 int r = 0;
188 dir = nbd_aio_get_direction (nbd);
190 if ((dir & LIBNBD_AIO_DIRECTION_READ) &&
192 a_read_event_occurred ())
193 r = nbd_aio_notify_read (nbd);
194 else if ((dir & LIBNBD_AIO_DIRECTION_WRITE) &&
195 a_write_event_occurred ())
196 r = nbd_aio_notify_write (nbd);
197 if (r == -1) {
199 fprintf (stderr, "%s\n", nbd_get_error ());
200 // ...
201 }
202 The notify calls move the state machine along, reading and writing from
204 the socket possibly multiple times, until the socket would block again,
205 at which point they return control to the caller.
206 Simple implementation with nbd_poll(3)
208 In fact if you want to use poll(2) on a single handle, a simple
209 implementation has already been written called nbd_poll(3). It is also
210 useful to examine how this is implemented (lib/poll.c in the libnbd
211 source code) because that will tell you how to integrate libnbd with
212 more complex main loops.
213 Some examples of using nbd_poll(3) follow.
215 As with the high level API, it all starts by creating a handle:
217 struct nbd_handle *nbd;
219 nbd = nbd_create ();
221 if (nbd == NULL) {
222 fprintf (stderr, "%s\n", nbd_get_error ());
223 nbd_close (nbd);
224 exit (EXIT_FAILURE);
225 }
226 To connect to the server asynchronously, we start the connection using
228 nbd_aio_connect(3) and then enter our main loop to check for events
229 until the connection becomes ready:
230 int fd;
232 struct sockaddr_un addr;
233 socklen_t len;
234 /* some code to set up addr,
236 then ... */
237 if (nbd_aio_connect (nbd, &addr, len) == -1) {
238 fprintf (stderr, "%s\n", nbd_get_error ());
239 nbd_close (nbd);
240 exit (EXIT_FAILURE);
241 }
242 while (! nbd_aio_is_ready (nbd)) {
243 if (nbd_poll (nbd, -1) == -1) {
244 fprintf (stderr, "%s\n", nbd_get_error ());
245 nbd_close (nbd);
246 exit (EXIT_FAILURE);
247 }
248 }
249 To read data asynchronously, start an asynchronous read command, which
251 returns a 64 bit command cookie, and enter the main loop until the
252 command has completed:
253 int64_t cookie;
255 char buf[512];
256 cookie = nbd_aio_pread (nbd, buf, sizeof buf, offset,
258 NBD_NULL_COMPLETION, 0);
259 if (cookie == -1) {
260 fprintf (stderr, "%s\n", nbd_get_error ());
261 nbd_close (nbd);
262 exit (EXIT_FAILURE);
263 }
264 while (! nbd_aio_command_completed (nbd, cookie)) {
265 if (nbd_poll (nbd, -1) == -1) {
266 fprintf (stderr, "%s\n", nbd_get_error ());
267 nbd_close (nbd);
268 exit (EXIT_FAILURE);
269 }
270 }
271 For almost all high level synchronous calls (eg. nbd_pread(3)) there is
273 a low level asynchronous equivalent (eg. nbd_aio_pread(3)) for starting
274 a command.
275 glib2 integration
277 See
278 https://github.com/libguestfs/libnbd/blob/master/examples/glib-main-loop.c
279
281 When any API call returns an error ("-1" or "NULL" depending on the
282 API), an error message and sometimes an errno value are available. You
283 can retrieve the error message and/or errno of the most recently failed
284 call using nbd_get_error(3) and nbd_get_errno(3). For example:
285 if (nbd_connect_tcp (nbd, "remote", "nbd") == -1) {
287 fprintf (stderr,
288 "failed to connect to remote server: %s (errno = %d)\n",
289 nbd_get_error (), nbd_get_errno ());
290 }
291 These functions use thread-local storage to return the most recent
293 error in the current thread. This is why you don't need to pass the
294 handle to these calls. They even work if nbd_create(3) returns "NULL"
295 when there is no handle at all.
296 For this reason you cannot call them from a different thread. You
298 should call them immediately after the failed API call, from the same
299 thread. Furthermore the error string returned by nbd_get_error(3) is
300 only valid until the next libnbd API call in the current thread, so if
301 you need to keep the string you must copy it (eg. using strdup(3)).
302 Errno
304 For some errors, a system call error number (see errno(3)) is
305 available. You can find the error number by calling nbd_get_errno(3).
306 It works the same way as nbd_get_error(3) with respect to threads.
307 Even when a call returns an error, nbd_get_errno(3) might return 0.
309 This does not mean there was no error. It means no additional errno
310 information is available for this error.
311 The error number is often the raw error returned by a system call that
313 failed.
314 It can also be used to indicate special conditions. The most common
316 cases are:
317 "EINVAL"
319 Invalid parameters or state for the current libnbd call.
320 "ENOTSUP"
322 The libnbd call is not available in this build of libnbd (eg. when
323 using a TLS API if the library was compiled without TLS support).
324 "ENOMEM"
326 The library ran out of memory while performing some operation.
327 "ERANGE"
329 A request is too large, for example if you try to read too many
330 bytes in a single nbd_pread(3) call.
331
333 Libnbd can print lots of debugging messages, useful if you have a
334 problem with the library. Either enable debugging after creating the
335 handle:
336 nbd = nbd_create ();
338 nbd_set_debug (nbd, true);
339 or set the "LIBNBD_DEBUG=1" environment variable which will enable
341 debugging by default on all new handles.
342 Debugging messages are sent to stderr by default, but you can redirect
344 them to a logging system using nbd_set_debug_callback(3).
345
347 There are several ways to connect to NBD servers, and you can even run
348 a server from libnbd. Normally you would connect to a server which is
349 already running, over a local Unix domain socket or a remote TCP
350 connection. The high level API calls are:
351 nbd_connect_unix (nbd, "socket");
353 nbd_connect_tcp (nbd, "localhost", "nbd");
354 For nbd_connect_tcp(3) the third parameter is the port name or number,
356 which can either be a name from /etc/services or the port number as a
357 string (eg. "10809").
358 Connecting to an NBD URI
360 libnbd supports the NBD URI specification. The URIs that libnbd
361 currently supports is documented in nbd_connect_uri(3).
362 You can connect to a URI as in these examples (using the high level
364 API):
365 nbd_connect_uri (nbd, "nbd://example.com/");
367 nbd_connect_uri (nbd, "nbds+unix:///export?socket=/tmp/nbd.sock");
369 This feature is implemented by calling other libnbd APIs to set up the
371 export name, TLS parameters, and finally connect over a Unix domain
372 socket or TCP.
373 URI support is an optional feature of the library, requiring libxml2 at
375 compile time. The nbd_connect_uri(3) and nbd_aio_connect_uri(3) calls
376 will raise an error (with nbd_get_errno(3) returning "ENOTSUP") if it
377 was not built with this feature, and you can also test for it
378 explicitly using nbd_supports_uri(3).
379 Connecting to a subprocess
381 Some NBD servers — notably nbdkit(1) with the -s parameter, and
382 nbd-server(1) with the port parameter set to 0 — can also accept a
383 single NBD connection on stdin/stdout. You can run these servers as a
384 subprocess of your main program using nbd_connect_command(3). This
385 example creates a 1G writable RAM disk:
386 char *argv[] = { "nbdkit", "-s", "--exit-with-parent",
388 "memory", "1G", NULL };
389 nbd_connect_command (nbd, argv);
390 When the handle is closed the nbdkit subprocess is killed, which in
392 this case means the RAM disk is discarded, so this is useful for
393 testing.
394 Connecting to a subprocess using systemd socket activation
396 Some NBD servers — notably nbdkit(1) and qemu-nbd(1) — support systemd
397 socket activation allowing libnbd to pass a socket to the subprocess.
398 This works very similarly to nbd_connect_command(3) described above,
399 but you must use nbd_connect_systemd_socket_activation(3) instead.
400
402 It is possible for NBD servers to serve different content on different
403 “exports”. For this you must pass the right export name to the server.
404 Call this API before connecting:
405 nbd_set_export_name (nbd, "export");
407 Note that there are some servers (like nbdkit(1) ≤ 1.14) which ignore
409 this, and other servers (like qemu-nbd(8)) which require it to be set
410 correctly but cannot serve different content.
411 Flag calls
413 After connecting the server will send back a set of flags describing
414 the export, such as whether it is writable and if it can support flush
415 to permanent storage. These flags can be accessed from libnbd using
416 APIs such as:
417 int is_read_only = nbd_is_read_only (nbd);
419 int can_flush = nbd_can_flush (nbd);
420 Flag calls are: nbd_can_cache(3), nbd_can_df(3), nbd_can_fast_zero(3),
422 nbd_can_flush(3), nbd_can_fua(3), nbd_can_meta_context(3),
423 nbd_can_multi_conn(3), nbd_can_trim(3), nbd_can_zero(3),
424 nbd_is_read_only(3), nbd_is_rotational(3).
425 Size of the export
427 To get the size of the export in bytes, use nbd_get_size(3):
428 int64_t size = nbd_get_size (nbd);
430
432 You can read and write data from the NBD server using nbd_pread(3) and
433 nbd_pwrite(3) or their asynchronous equivalents.
434 Some servers also support:
436 trim/discard
438 If nbd_can_trim(3) returns true, nbd_trim(3) can be used to “punch
439 holes” in the backing storage of the disk on the server. Normally
440 (although not in every case) the holes read back as zeroes but take
441 up no space.
442 zeroing
444 If nbd_can_zero(3) returns true, nbd_zero(3) can be used to
445 efficiently zero parts of the disk without having to send large
446 amounts of zero bytes over the network (as would be necessary if
447 using nbd_pwrite(3)).
448 This is slightly different from trimming because the backing
450 storage is still allocated. For some storage types this can make
451 future writes more efficient and/or less likely to fail because of
452 out of space errors.
453 flushing
455 Some servers can commit data to permanent storage and tell you that
456 this has happened reliably. There are two export flags associated
457 with this: nbd_can_flush(3) and nbd_can_fua(3).
458 The nbd_flush(3) call (available if nbd_can_flush(3) returns true)
460 flushes all pending writes to disk and does not complete until that
461 operation has finished. It is similar to using sync(2) on POSIX
462 systems.
463 A more efficient way to achieve this is to set the flag
465 "LIBNBD_CMD_FLAG_FUA" on write-like calls (like write, trim and
466 zero). This flag means the call will not complete until committed
467 to permanent storage, but it does not involve flushing the entire
468 disk.
469 prefetching
471 Some servers can prefetch data, making subsequent reads faster.
472 The nbd_cache(3) call (available if nbd_can_cache(3) returns true)
473 is used to prefetch.
474 block status
476 Some servers are able to provide information about the various
477 extents within the image, via the notion of one or more meta
478 contexts. The most common meta context is "base:allocation"
479 (available in libnbd.h as "LIBNBD_CONTEXT_BASE_ALLOCATION"), which
480 can be used to learn which portions of a file are allocated or read
481 as zero. Other contexts may be available; for example, qemu-nbd(8)
482 can expose a meta context "qemu:dirty-bitmap:NAME" for tracking
483 which portions of a file are tracked by a qcow2 dirty bitmap.
484 In order to utilize block status, the client must call
486 nbd_add_meta_context(3) prior to connecting, for each meta context
487 in which it is interested, then check nbd_can_meta_context(3) after
488 connection to see which contexts the server actually supports. If
489 a context is supported, the client can then use nbd_block_status(3)
490 with a callback function that will receive an array of 32-bit
491 integer pairs describing consecutive extents within a context. In
492 each pair, the first integer is the length of the extent, the
493 second is a bitmask description of that extent (for the
494 "base:allocation" context, the bitmask may include
495 "LIBNBD_STATE_HOLE" for unallocated portions of the file, and/or
496 "LIBNBD_STATE_ZERO" for portions of the file known to read as
497 zero).
498 There is a full example of requesting meta context and using block
500 status available at
501 https://github.com/libguestfs/libnbd/blob/master/interop/dirty-bitmap.c
502
504 Issuing multiple in-flight requests
505 NBD servers which properly implement the specification can handle
506 multiple requests in flight over the same connection at the same time.
507 Libnbd supports this when using the low level API.
508 To use it you simply issue more requests as needed (eg. using calls
510 like nbd_aio_pread(3), nbd_aio_pwrite(3)) without waiting for previous
511 commands to complete. You need to be careful that requests in flight
512 do not overlap with disk offsets of other write-like commands in flight
513 — an overlapping read may see indeterminate data, and an overlapping
514 write may even cause disk corruption where the resulting disk contents
515 do not match either of the two writes.
516 Each request is identified by a unique 64 bit cookie (assigned by
518 libnbd), allowing libnbd and callers to match replies to requests.
519 Replies may arrive out of order.
520 Although in theory you can have an indefinite number of requests in
522 flight at the same time, in practice it's a good idea to limit them to
523 some number. Libnbd will queue commands in the handle even if it
524 cannot write them to the server, so this limit is largely to prevent a
525 backlog of commands from consuming too much memory. It is suggested to
526 start with a limit of 64 requests in flight (per NBD connection), and
527 measure how adjusting the limit up and down affects performance for
528 your local configuration.
529 There is a full example using multiple in-flight requests available at
531 https://github.com/libguestfs/libnbd/blob/master/examples/threaded-reads-and-writes.c
532 Multi-conn
534 Some NBD servers advertise “multi-conn” which means that it is safe to
535 make multiple connections to the server and load-balance commands
536 across all of the connections.
537 To do this you should open a single connection first and test for this
539 feature using nbd_can_multi_conn(3). Without error handling it would
540 look like this:
541 struct nbd_handle *nbd[4];
543 size_t i;
544 bool supports_multi_conn;
545 nbd[0] = nbd_create ();
547 nbd_connect_tcp (nbd[0], "server", "10809");
548 supports_multi_conn = nbd_can_multi_conn (nbd[0]) > 0;
549 If multi-conn is supported then you can open further connections:
551 if (supports_multi_conn) {
553 for (i = 1; i <= 3; ++i) {
554 nbd[i] = nbd_create ();
555 nbd_connect_tcp (nbd[i], "server", "10809");
556 }
557 }
558 If you are issuing multiple in-flight requests (see above) and limiting
560 the number, then the limit should be applied to each individual NBD
561 connection.
562
564 The NBD protocol and libnbd supports TLS (sometimes incorrectly called
565 “SSL”) for encryption of the data stream and authentication of clients
566 and servers. Libnbd defaults to TLS disabled for maximum
567 interoperability. To enable it on a handle you must call
568 nbd_set_tls(3) before connecting.
569 To allow TLS, but fall back to unencrypted:
571 nbd_set_tls (nbd, LIBNBD_TLS_ALLOW);
573 Use nbd_get_tls_negotiated(3) to find out if TLS negotiation was
575 successful. Avoid "LIBNBD_TLS_ALLOW" if man-in-the-middle attacks are
576 a concern.
577 The most secure mode is to require TLS and fail to connect if the
579 server does not support it:
580 nbd_set_tls (nbd, LIBNBD_TLS_REQUIRE);
582 It may also be necessary to verify that the server’s identity is
584 correct. For some servers it may be necessary to verify to the server
585 that the client is permitted to connect. This can be done using either
586 X.509 certificates, or TLS Pre-Shared Keys (PSK). Certificates are
587 more secure. PSK is far more convenient, but you must have an existing
588 secure channel to distribute the keys.
589 Setting up X.509 using system certificate authorities (CAs)
591 This is the default if you don’t call any other "nbd_set_tls_*"
592 functions. In this case the server must have a public (eg. HTTPS)
593 certificate which can be verified against the CAs registered on your
594 system (eg. under /etc/pki).
595 To disable server name verification — which opens you up to a potential
597 Man-In-The-Middle (MITM) attack — use:
598 nbd_set_tls_verify_peer (nbd, false);
600 Setting up an X.509 certificate authority (CA)
602 You can set up your own CA and register clients and servers with it,
603 issuing client and server certificates which will reliably authenticate
604 your clients and servers to each other.
605 Doing this is described in detail in the nbdkit-tls(1) manual. The
607 only differences for libnbd are:
608 · Non-root certificates must be placed in "$HOME/.pki/libnbd/" or
610 "$HOME/.config/pki/libnbd/"
611 · Libnbd reads client-cert.pem and client-key.pem (instead of
613 server-cert.pem and server-key.pem).
614 Once you have set up the directory containing the certificates, call:
616 nbd_set_tls_certificates (nbd, "/path/to/directory");
618 Setting up Pre-Shared Keys (PSK)
620 TLS Pre-Shared Keys are a much more convenient method of setting up
621 TLS, and more appropriate for NBD, but you should have an existing
622 secure method available to distribute the keys. They are therefore
623 ideal if you want to set up an NBD service as an adjunct to an existing
624 secure REST API.
625 Use psktool(1) to create a file of "username:key" pairs:
627 psktool -u username -p keys.psk
629 and pass this path to libnbd:
631 nbd_set_tls_psk_file (nbd, "keys.psk");
633 If necessary you may need to set the client username (otherwise libnbd
635 will use your login name):
636 nbd_set_tls_username (nbd, "username");
638
640 Some libnbd calls take callbacks (eg. nbd_set_debug_callback(3),
641 nbd_aio_pread(3)). Libnbd can call these functions while processing.
642 In the C API these libnbd calls take a structure which contains the
644 function pointer and an optional opaque "void *user_data" pointer:
645 nbd_aio_pread (nbd, buf, sizeof buf, offset,
647 (nbd_completion_callback) { .callback = my_fn,
648 .user_data = my_data },
649 0);
650 For optional callbacks, if you don't want the callback, either set
652 ".callback" to "NULL" or use the equivalent macros (such as
653 "NBD_NULL_COMPLETION") defined in "libnbd.h":
654 nbd_aio_pread (nbd, buf, sizeof buf, offset,
656 NBD_NULL_COMPLETION, 0);
657 From other languages the structure and opaque pointer are not needed
659 because you can use closures to achieve the same effect.
660 Callback lifetimes
662 You can associate an optional free function with callbacks. Libnbd
663 will call this function when the callback will not be called again by
664 libnbd.
665 This can be used to free associated "user_data". For example:
667 void *my_data = malloc (...);
669 nbd_aio_pread_structured (nbd, buf, sizeof buf, offset,
671 (nbd_chunk_callback) { .callback = my_fn,
672 .user_data = my_data,
673 .free = free },
674 NBD_NULL_CALLBACK(completion),
675 0);
676 will call free(3) on "my_data" after the last time that the
678 "chunk.callback = my_fn" function is called.
679 The free function is only accessible in the C API as it is not needed
681 in garbage collected programming languages.
682 Callbacks with ".callback=NULL" and ".free!=NULL"
684 It is possible to register a callback like this:
685 ...
687 (nbd_completion_callback) { .callback = NULL,
688 .user_data = my_data,
689 .free = free },
690 ...
691 The meaning of this is that the callback is never called, but the free
693 function is still called after the last time the callback would have
694 been called. This is useful for applying generic freeing actions when
695 asynchronous commands are retired.
696 Callbacks and locking
698 The callbacks are invoked at a point where the libnbd lock is held; as
699 such, it is unsafe for the callback to call any "nbd_*" APIs on the
700 same nbd object, as it would cause deadlock.
701 Completion callbacks
703 All of the low-level commands have a completion callback variant that
704 registers a callback function used right before the command is marked
705 complete.
706 When the completion callback returns 1, the command is automatically
708 retired (there is no need to call nbd_aio_command_completed(3)); for
709 any other return value, the command still needs to be retired.
710 Callbacks with "int *error" parameter
712 Some of the high-level commands (nbd_pread_structured(3),
713 nbd_block_status(3)) involve the use of a callback function invoked by
714 the state machine at appropriate points in the server's reply before
715 the overall command is complete. These callback functions, along with
716 all of the completion callbacks, include a parameter "error" containing
717 the value of any error detected so far; if the callback function fails,
718 it should assign back into "error" and return "-1" to change the
719 resulting error of the overall command. Assignments into "error" are
720 ignored for any other return value; similarly, assigning 0 into "error"
721 does not have an effect.
722
724 On most systems, C programs that use libnbd can be compiled like this:
725 cc prog.c -o prog -lnbd
727 To detect if the libnbd library and header file is installed, the
729 preferred method is to use pkg-config(1) or pkgconf(1):
730 pkg-config libnbd --exists || fail libnbd is required
732 In case the library or header file are not installed in the usual
734 system locations, you can compile your program like this, using pkg-
735 config to detect the proper location of libnbd:
736 cc prog.c -o prog `pkg-config libnbd --cflags --libs`
738 External projects which use autoconf and need to check if libnbd is
740 installed should use the "PKG_CHECK_MODULES" macro in configure.ac like
741 this:
742 PKG_CHECK_MODULES([LIBNBD], [libnbd])
744 This will define "@LIBNBD_CFLAGS@" and "@LIBNBD_LIBS@" which you will
746 need to add to your Makefile.am.
747 For CMake projects use:
749 find_package(PkgConfig REQUIRED)
751 pkg_check_modules(LIBNBD REQUIRED libnbd)
752 target_link_libraries(prog ${LIBNBD_LIBRARIES})
753 target_include_directories(prog PUBLIC ${LIBNBD_INCLUDE_DIRS})
754 target_compile_options(prog PUBLIC ${LIBNBD_CFLAGS_OTHER})
755 To compile an external project against a built copy of the libnbd
757 source tree which hasn't been installed, see the ./run script.
758
760 "HOME"
761 Used in some situations to find TLS certificates. See
762 nbd_set_tls_certificates(3).
763 "LIBNBD_DEBUG"
765 If this is set to the exact string 1 when the handle is created
766 then debugging is enabled. See "DEBUGGING MESSAGES" above.
767 "LOGNAME"
769 The default TLS username. See nbd_set_tls_username(3).
770
772 C API
773 nbd_add_meta_context(3), nbd_aio_block_status(3), nbd_aio_cache(3),
774 nbd_aio_command_completed(3), nbd_aio_connect(3),
775 nbd_aio_connect_command(3), nbd_aio_connect_socket(3),
776 nbd_aio_connect_systemd_socket_activation(3), nbd_aio_connect_tcp(3),
777 nbd_aio_connect_unix(3), nbd_aio_connect_uri(3),
778 nbd_aio_connect_vsock(3), nbd_aio_disconnect(3), nbd_aio_flush(3),
779 nbd_aio_get_direction(3), nbd_aio_get_fd(3), nbd_aio_in_flight(3),
780 nbd_aio_is_closed(3), nbd_aio_is_connecting(3), nbd_aio_is_created(3),
781 nbd_aio_is_dead(3), nbd_aio_is_processing(3), nbd_aio_is_ready(3),
782 nbd_aio_notify_read(3), nbd_aio_notify_write(3),
783 nbd_aio_peek_command_completed(3), nbd_aio_pread(3),
784 nbd_aio_pread_structured(3), nbd_aio_pwrite(3), nbd_aio_trim(3),
785 nbd_aio_zero(3), nbd_block_status(3), nbd_cache(3), nbd_can_cache(3),
786 nbd_can_df(3), nbd_can_fast_zero(3), nbd_can_flush(3), nbd_can_fua(3),
787 nbd_can_meta_context(3), nbd_can_multi_conn(3), nbd_can_trim(3),
788 nbd_can_zero(3), nbd_clear_debug_callback(3), nbd_close(3),
789 nbd_connect_command(3), nbd_connect_socket(3),
790 nbd_connect_systemd_socket_activation(3), nbd_connect_tcp(3),
791 nbd_connect_unix(3), nbd_connect_uri(3), nbd_connect_vsock(3),
792 nbd_connection_state(3), nbd_create(3), nbd_flush(3), nbd_get_debug(3),
793 nbd_get_errno(3), nbd_get_error(3), nbd_get_export_name(3),
794 nbd_get_handle_name(3), nbd_get_handshake_flags(3),
795 nbd_get_package_name(3), nbd_get_protocol(3),
796 nbd_get_request_structured_replies(3), nbd_get_size(3),
797 nbd_get_structured_replies_negotiated(3), nbd_get_tls(3),
798 nbd_get_tls_negotiated(3), nbd_get_tls_username(3),
799 nbd_get_tls_verify_peer(3), nbd_get_version(3), nbd_is_read_only(3),
800 nbd_is_rotational(3), nbd_kill_subprocess(3), nbd_poll(3),
801 nbd_pread(3), nbd_pread_structured(3), nbd_pwrite(3), nbd_set_debug(3),
802 nbd_set_debug_callback(3), nbd_set_export_name(3),
803 nbd_set_handle_name(3), nbd_set_handshake_flags(3),
804 nbd_set_request_structured_replies(3), nbd_set_tls(3),
805 nbd_set_tls_certificates(3), nbd_set_tls_psk_file(3),
806 nbd_set_tls_username(3), nbd_set_tls_verify_peer(3),
807 nbd_set_uri_allow_local_file(3), nbd_set_uri_allow_tls(3),
808 nbd_set_uri_allow_transports(3), nbd_shutdown(3), nbd_supports_tls(3),
809 nbd_supports_uri(3), nbd_trim(3), nbd_zero(3).
810 Servers
812 nbdkit(1), nbd-server(1), qemu-nbd(8).
813 Encryption tools
815 certtool(1), nbdkit-tls(1), psktool(1).
816 Standards
818 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
819 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md.
820 Other
822 libnbd-release-notes-1.4(1), libnbd-release-notes-1.2(1),
823 libnbd-security(3), nbdfuse(1), nbdsh(1), qemu(1).
824
826 Eric Blake
827 Richard W.M. Jones
829
831 Copyright (C) 2019-2020 Red Hat Inc.
832
834 This library is free software; you can redistribute it and/or modify it
835 under the terms of the GNU Lesser General Public License as published
836 by the Free Software Foundation; either version 2 of the License, or
837 (at your option) any later version.
838 This library is distributed in the hope that it will be useful, but
840 WITHOUT ANY WARRANTY; without even the implied warranty of
841 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
842 Lesser General Public License for more details.
843 You should have received a copy of the GNU Lesser General Public
845 License along with this library; if not, write to the Free Software
846 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
847 02110-1301 USA
848libnbd-1.3.7 2020-04-23 libnbd(3)