1libnbd-api(3) LIBNBD libnbd-api(3)
2
6 libnbd-api - libnbd C API
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 exit (EXIT_FAILURE);
19 }
20 nbd_close (nbd);
21 cc prog.c -o prog -lnbd
23 or:
24 cc prog.c -o prog `pkg-config libnbd --cflags --libs`
25
27 This manual page describes all of the libnbd API calls from C in
28 detail. If you want an overview of using the API, or to see how to
29 call the API from other programming languages, start with libnbd(3).
30 For the sake of conditional compilation across a range of libnbd
32 versions, where a client may take advantage of newer API when present
33 but gracefully continue to compile even when it is not, all functions
34 declared in <libnbd.h> have a corresponding witness macro with prefix
35 "LIBNBD_HAVE_". For example, "nbd_create" has a counterpart macro
36 "LIBNBD_HAVE_NBD_CREATE" defined to 1.
37
39 struct nbd_handle *nbd;
40 This opaque structure describes an NBD client handle and connection to
42 an NBD server.
43 struct nbd_handle *nbd_create (void);
45 Create a new handle. Returns a pointer to the opaque handle structure.
47 On error this returns "NULL". See "ERROR HANDLING" in libnbd(3) for
49 how to get further details of the error.
50 void nbd_close (struct nbd_handle *nbd);
52 Closes the handle frees any associated resources.
54
56 See "ERROR HANDLING" in libnbd(3) for more discussion of how error
57 handling works in libnbd.
58 const char *nbd_get_error (void);
60 Return the most recent error message in the current thread. The error
62 message is only valid if called immediately after the failing call,
63 from the same thread. The error string returned will be freed up next
64 time any libnbd API is called from the same thread, so if you need to
65 keep it you must make a copy.
66 This should never return "NULL" provided there was an error returned
68 from the immediately preceding libnbd call in the current thread.
69 int nbd_get_errno (void);
71 Return the most recent "errno" in the current thread. Not all errors
73 have corresponding errnos, so even if there has been an error this may
74 return 0. Error codes are the standard ones from "<errno.h>".
75
77 You can register close callbacks with the handle. These are called
78 when "nbd_close" is called. The order in which they are called is not
79 defined. This API is only available from C and is designed to help
80 when writing bindings to libnbd from other programming languages.
81 typedef void (*nbd_close_callback) (void *data);
83 int nbd_add_close_callback (struct nbd_handle *nbd,
84 nbd_close_callback cb, void *data);
85
87 set_debug — set or clear the debug flag
88 int nbd_set_debug (struct nbd_handle *h, bool debug);
89 Set or clear the debug flag. When debugging is enabled, debugging
91 messages from the library are printed to stderr, unless a debugging
92 callback has been defined too (see "nbd_set_debug_callback") in which
93 case they are sent to that function. This flag defaults to false on
94 newly created handles, except if "LIBNBD_DEBUG=1" is set in the
95 environment in which case it defaults to true.
96 If the call is successful the function returns 0.
98 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
100 to get further details of the error.
101 get_debug — return the state of the debug flag
103 int nbd_get_debug (struct nbd_handle *h);
104 Return the state of the debug flag on this handle.
106 This call returns a boolean value.
108 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
110 to get further details of the error.
111 set_debug_callback — set the debug callback
113 int nbd_set_debug_callback (struct nbd_handle *h, void *data, int (*debug_fn) (void *data, const char *context, const char *msg));
114 Set the debug callback. This function is called when the library emits
116 debug messages, when debugging is enabled on a handle. The callback
117 parameters are "data" passed to this function, the name of the libnbd
118 function emitting the debug message ("context"), and the message itself
119 ("msg"). If no debug callback is set on a handle then messages are
120 printed on "stderr".
121 The callback should not call "nbd_*" APIs on the same handle since it
123 can be called while holding the handle lock and will cause a deadlock.
124 If the call is successful the function returns 0.
126 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
128 to get further details of the error.
129 set_export_name — set the export name
131 int nbd_set_export_name (struct nbd_handle *h, const char *export_name);
132 For servers which require an export name or can serve different content
134 on different exports, set the "export_name" to connect to. This is
135 only relevant for the newstyle protocol. This call may be skipped if
136 using "nbd_connect_uri" to connect to a URI that includes an export
137 name. The default is to use the empty string.
138 The handle must be newly created, otherwise this call will return an
140 error.
141 If the call is successful the function returns 0.
143 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
145 to get further details of the error.
146 get_export_name — get the export name
148 char *nbd_get_export_name (struct nbd_handle *h);
149 Get the export name associated with the handle.
151 This call returns a string. The caller must free the returned string
153 to avoid a memory leak.
154 On error "NULL" is returned. See "ERROR HANDLING" in libnbd(3) for how
156 to get further details of the error.
157 set_tls — enable or require TLS (authentication and encryption)
159 int nbd_set_tls (struct nbd_handle *h, int tls);
160 Enable or require TLS (authenticated and encrypted connections) to the
162 NBD server. The possible settings are:
163 "tls=0"
165 Disable TLS. (The default setting, unless using "nbd_connect_uri"
166 with a URI that requires TLS)
167 "tls=1"
169 Enable TLS if possible. In some cases this will fall back to an
170 unencrypted and/or unauthenticated connection if TLS could not be
171 established. However some servers will drop the connection if TLS
172 fails so fallback may not be possible.
173 "tls=2"
175 Require an encrypted and authenticated TLS connection. Always fail
176 to connect if the connection is not encrypted and authenticated.
177 As well as calling this you may also need to supply the path to the
179 certificates directory ("nbd_set_tls_certificates"), the username
180 ("nbd_set_tls_username") and/or the Pre-Shared Keys (PSK) file
181 ("nbd_set_tls_psk_file"). For now, when using "nbd_connect_uri", any
182 URI query parameters related to TLS are not handled automatically.
183 Setting the level higher than zero will fail if libnbd was not compiled
184 against gnutls; you can test whether this is the case with
185 "nbd_supports_tls".
186 For more information see "ENCRYPTION AND AUTHENTICATION" in libnbd(3).
188 The handle must be newly created, otherwise this call will return an
190 error.
191 If the call is successful the function returns 0.
193 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
195 to get further details of the error.
196 get_tls — get the current TLS setting
198 int nbd_get_tls (struct nbd_handle *h);
199 Get the current TLS setting. See "nbd_set_tls".
201 This call returns an integer ≥ 0.
203 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
205 to get further details of the error.
206 set_tls_certificates — set the path to the TLS certificates directory
208 int nbd_set_tls_certificates (struct nbd_handle *h, const char *dir);
209 Set the path to the TLS certificates directory. If not set and TLS is
211 used then a compiled in default is used. For root this is
212 "/etc/pki/libnbd/". For non-root this is "$HOME/.pki/libnbd" and
213 "$HOME/.config/pki/libnbd". If none of these directories can be found
214 then the system trusted CAs are used.
215 This function may be called regardless of whether TLS is supported, but
217 will have no effect unless "nbd_set_tls" is also used to request or
218 require TLS.
219 The handle must be newly created, otherwise this call will return an
221 error.
222 If the call is successful the function returns 0.
224 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
226 to get further details of the error.
227 set_tls_verify_peer — set whether we verify the identity of the server
229 int nbd_set_tls_verify_peer (struct nbd_handle *h, bool verify);
230 Set this flag to control whether libnbd will verify the identity of the
232 server from the server's certificate and the certificate authority.
233 This defaults to true when connecting to TCP servers using TLS
234 certificate authentication, and false otherwise.
235 This function may be called regardless of whether TLS is supported, but
237 will have no effect unless "nbd_set_tls" is also used to request or
238 require TLS.
239 The handle must be newly created, otherwise this call will return an
241 error.
242 If the call is successful the function returns 0.
244 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
246 to get further details of the error.
247 get_tls_verify_peer — get whether we verify the identity of the server
249 int nbd_get_tls_verify_peer (struct nbd_handle *h);
250 Get the verify peer flag.
252 This call returns a boolean value.
254 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
256 to get further details of the error.
257 set_tls_username — set the TLS username
259 int nbd_set_tls_username (struct nbd_handle *h, const char *username);
260 Set the TLS client username. This is used if authenticating with PSK
262 over TLS is enabled. If not set then the local username is used.
263 This function may be called regardless of whether TLS is supported, but
265 will have no effect unless "nbd_set_tls" is also used to request or
266 require TLS.
267 The handle must be newly created, otherwise this call will return an
269 error.
270 If the call is successful the function returns 0.
272 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
274 to get further details of the error.
275 get_tls_username — get the current TLS username
277 char *nbd_get_tls_username (struct nbd_handle *h);
278 Get the current TLS username. See "nbd_set_tls_username".
280 This call returns a string. The caller must free the returned string
282 to avoid a memory leak.
283 On error "NULL" is returned. See "ERROR HANDLING" in libnbd(3) for how
285 to get further details of the error.
286 set_tls_psk_file — set the TLS Pre-Shared Keys (PSK) filename
288 int nbd_set_tls_psk_file (struct nbd_handle *h, const char *filename);
289 Set the TLS Pre-Shared Keys (PSK) filename. This is used if trying to
291 authenticate to the server using with a pre-shared key. There is no
292 default so if this is not set then PSK authentication cannot be used to
293 connect to the server.
294 This function may be called regardless of whether TLS is supported, but
296 will have no effect unless "nbd_set_tls" is also used to request or
297 require TLS.
298 The handle must be newly created, otherwise this call will return an
300 error.
301 If the call is successful the function returns 0.
303 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
305 to get further details of the error.
306 add_meta_context — ask server to negotiate metadata context
308 int nbd_add_meta_context (struct nbd_handle *h, const char *name);
309 During connection libnbd can negotiate zero or more metadata contexts
311 with the server. Metadata contexts are features (such as
312 "base:allocation") which describe information returned by the
313 "nbd_block_status" command (for "base:allocation" this is whether
314 blocks of data are allocated, zero or sparse).
315 This call adds one metadata context to the list to be negotiated. You
317 can call it as many times as needed. The list is initially empty when
318 the handle is created.
319 Not all servers support all metadata contexts. To learn if a context
321 was actually negotiated, call "nbd_can_meta_context" after connecting.
322 The single parameter is the name of the metadata context, for example
324 "base:allocation".
325 Other metadata contexts are server-specific, but include
327 "qemu:dirty-bitmap:..." for qemu-nbd (see qemu-nbd -B option). See
328 also "nbd_block_status".
329 The handle must be newly created, otherwise this call will return an
331 error.
332 If the call is successful the function returns 0.
334 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
336 to get further details of the error.
337 connect_uri — connect to NBD URI
339 int nbd_connect_uri (struct nbd_handle *h, const char *uri);
340 Connect (synchronously) to an NBD server and export by specifying the
342 NBD URI. This call parses the URI and may call "nbd_set_export_name"
343 and "nbd_set_tls" as needed, followed by "nbd_connect_tcp" or
344 "nbd_connect_unix". This call returns when the connection has been
345 made.
346 This call will fail if libnbd was not compiled with libxml2; you can
348 test whether this is the case with "nbd_supports_uri". Support for
349 URIs that require TLS will fail if libnbd was not compiled with gnutls;
350 you can test whether this is the case with "nbd_supports_tls".
351 The handle must be newly created, otherwise this call will return an
353 error.
354 If the call is successful the function returns 0.
356 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
358 to get further details of the error.
359 connect_unix — connect to NBD server over a Unix domain socket
361 int nbd_connect_unix (struct nbd_handle *h, const char *unixsocket);
362 Connect (synchronously) over the named Unix domain socket
364 ("unixsocket") to an NBD server running on the same machine. This call
365 returns when the connection has been made.
366 The handle must be newly created, otherwise this call will return an
368 error.
369 If the call is successful the function returns 0.
371 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
373 to get further details of the error.
374 connect_tcp — connect to NBD server over a TCP port
376 int nbd_connect_tcp (struct nbd_handle *h, const char *hostname, const char *port);
377 Connect (synchronously) to the NBD server listening on "hostname:port".
379 The "port" may be a port name such as "nbd", or it may be a port number
380 as a string such as "10809". This call returns when the connection has
381 been made.
382 The handle must be newly created, otherwise this call will return an
384 error.
385 If the call is successful the function returns 0.
387 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
389 to get further details of the error.
390 connect_command — connect to NBD server command
392 int nbd_connect_command (struct nbd_handle *h, char **argv);
393 Run the command as a subprocess and connect to it over stdin/stdout.
395 This is for use with NBD servers which can behave like inetd clients,
396 such as "nbdkit --single".
397 The handle must be newly created, otherwise this call will return an
399 error.
400 If the call is successful the function returns 0.
402 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
404 to get further details of the error.
405 read_only — is the NBD export read-only?
407 int nbd_read_only (struct nbd_handle *h);
408 Returns true if the NBD export is read-only; writes and write-like
410 operations will fail.
411 The handle must be connected and finished handshaking with the server,
413 or closed, otherwise this call will return an error.
414 This call returns a boolean value.
416 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
418 to get further details of the error.
419 can_flush — does the server support the flush command?
421 int nbd_can_flush (struct nbd_handle *h);
422 Returns true if the server supports the flush command (see "nbd_flush",
424 "nbd_aio_flush"). Returns false if the server does not.
425 The handle must be connected and finished handshaking with the server,
427 or closed, otherwise this call will return an error.
428 This call returns a boolean value.
430 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
432 to get further details of the error.
433 can_fua — does the server support the FUA flag?
435 int nbd_can_fua (struct nbd_handle *h);
436 Returns true if the server supports the FUA flag on certain commands
438 (see "nbd_pwrite").
439 The handle must be connected and finished handshaking with the server,
441 or closed, otherwise this call will return an error.
442 This call returns a boolean value.
444 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
446 to get further details of the error.
447 is_rotational — is the NBD disk rotational (like a disk)?
449 int nbd_is_rotational (struct nbd_handle *h);
450 Returns true if the disk exposed over NBD is rotational (like a
452 traditional floppy or hard disk). Returns false if the disk has no
453 penalty for random access (like an SSD or RAM disk).
454 The handle must be connected and finished handshaking with the server,
456 or closed, otherwise this call will return an error.
457 This call returns a boolean value.
459 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
461 to get further details of the error.
462 can_trim — does the server support the trim command?
464 int nbd_can_trim (struct nbd_handle *h);
465 Returns true if the server supports the trim command (see "nbd_trim",
467 "nbd_aio_trim"). Returns false if the server does not.
468 The handle must be connected and finished handshaking with the server,
470 or closed, otherwise this call will return an error.
471 This call returns a boolean value.
473 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
475 to get further details of the error.
476 can_zero — does the server support the zero command?
478 int nbd_can_zero (struct nbd_handle *h);
479 Returns true if the server supports the zero command (see "nbd_zero",
481 "nbd_aio_zero"). Returns false if the server does not.
482 The handle must be connected and finished handshaking with the server,
484 or closed, otherwise this call will return an error.
485 This call returns a boolean value.
487 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
489 to get further details of the error.
490 can_multi_conn — does the server support multi-conn?
492 int nbd_can_multi_conn (struct nbd_handle *h);
493 Returns true if the server supports multi-conn. Returns false if the
495 server does not.
496 It is not safe to open multiple handles connecting to the same server
498 if you will write to the server and the server does not advertize
499 multi-conn support. The safe way to check for this is to open one
500 connection, check this flag is true, then open further connections as
501 required.
502 The handle must be connected and finished handshaking with the server,
504 or closed, otherwise this call will return an error.
505 This call returns a boolean value.
507 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
509 to get further details of the error.
510 can_cache — does the server support the cache command?
512 int nbd_can_cache (struct nbd_handle *h);
513 Returns true if the server supports the cache command (see "nbd_cache",
515 "nbd_aio_cache"). Returns false if the server does not.
516 The handle must be connected and finished handshaking with the server,
518 or closed, otherwise this call will return an error.
519 This call returns a boolean value.
521 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
523 to get further details of the error.
524 can_meta_context — does the server support a specific meta context?
526 int nbd_can_meta_context (struct nbd_handle *h, const char *metacontext);
527 Returns true if the server supports the given meta context (see
529 "nbd_add_meta_context"). Returns false if the server does not.
530 The single parameter is the name of the metadata context, for example
532 "base:allocation".
533 The handle must be connected and finished handshaking with the server,
535 or closed, otherwise this call will return an error.
536 This call returns a boolean value.
538 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
540 to get further details of the error.
541 get_size — return the export size
543 int64_t nbd_get_size (struct nbd_handle *h);
544 Returns the size in bytes of the NBD export.
546 The handle must be connected and finished handshaking with the server,
548 or closed, otherwise this call will return an error.
549 This call returns a 64 bit signed integer ≥ 0.
551 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
553 to get further details of the error.
554 pread — read from the NBD server
556 int nbd_pread (struct nbd_handle *h, void *buf, size_t count, uint64_t offset, uint32_t flags);
557 Issue a read command to the NBD server for the range starting at
559 "offset" and ending at "offset" + "count" - 1. NBD can only read all
560 or nothing using this call. The call returns when the data has been
561 read fully into "buf" or there is an error.
562 The "flags" parameter must be 0 for now (it exists for future NBD
564 protocol extensions).
565 The handle must be connected and finished handshaking with the server,
567 otherwise this call will return an error.
568 If the call is successful the function returns 0.
570 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
572 to get further details of the error.
573 pwrite — write to the NBD server
575 int nbd_pwrite (struct nbd_handle *h, const void *buf, size_t count, uint64_t offset, uint32_t flags);
576 Issue a write command to the NBD server, writing the data in "buf" to
578 the range starting at "offset" and ending at "offset" + "count" - 1.
579 NBD can only write all or nothing using this call. The call returns
580 when the command has been acknowledged by the server, or there is an
581 error.
582 The "flags" parameter may be 0 for no flags, or may contain
584 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
585 the data has been committed to permanent storage (if that is supported
586 - some servers cannot do this, see "nbd_can_fua").
587 The handle must be connected and finished handshaking with the server,
589 otherwise this call will return an error.
590 If the call is successful the function returns 0.
592 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
594 to get further details of the error.
595 shutdown — disconnect from the NBD server
597 int nbd_shutdown (struct nbd_handle *h);
598 Issue the disconnect command to the NBD server. This is a nice way to
600 tell the server we are going away, but from the client's point of view
601 has no advantage over abruptly closing the connection (see
602 "nbd_close").
603 This function works whether or not the handle is ready for transmission
605 of commands, and as such does not take a "flags" parameter. If more
606 fine-grained control is needed, see "nbd_aio_disconnect".
607 The handle must be connected and finished handshaking with the server,
609 otherwise this call will return an error.
610 If the call is successful the function returns 0.
612 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
614 to get further details of the error.
615 flush — send flush command to the NBD server
617 int nbd_flush (struct nbd_handle *h, uint32_t flags);
618 Issue the flush command to the NBD server. The function should return
620 when all write commands which have completed have been committed to
621 permanent storage on the server. Note this will return an error if
622 "nbd_can_flush" is false.
623 The "flags" parameter must be 0 for now (it exists for future NBD
625 protocol extensions).
626 The handle must be connected and finished handshaking with the server,
628 otherwise this call will return an error.
629 If the call is successful the function returns 0.
631 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
633 to get further details of the error.
634 trim — send trim command to the NBD server
636 int nbd_trim (struct nbd_handle *h, uint64_t count, uint64_t offset, uint32_t flags);
637 Issue a trim command to the NBD server, which if supported by the
639 server causes a hole to be punched in the backing store starting at
640 "offset" and ending at "offset" + "count" - 1. The call returns when
641 the command has been acknowledged by the server, or there is an error.
642 The "flags" parameter may be 0 for no flags, or may contain
644 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
645 the data has been committed to permanent storage (if that is supported
646 - some servers cannot do this, see "nbd_can_fua").
647 The handle must be connected and finished handshaking with the server,
649 otherwise this call will return an error.
650 If the call is successful the function returns 0.
652 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
654 to get further details of the error.
655 cache — send cache (prefetch) command to the NBD server
657 int nbd_cache (struct nbd_handle *h, uint64_t count, uint64_t offset, uint32_t flags);
658 Issue the cache (prefetch) command to the NBD server, which if
660 supported by the server causes data to be prefetched into faster
661 storage by the server, speeding up a subsequent "nbd_pread" call. The
662 server can also silently ignore this command. Note this will return an
663 error if "nbd_can_cache" is false.
664 The "flags" parameter must be 0 for now (it exists for future NBD
666 protocol extensions).
667 The handle must be connected and finished handshaking with the server,
669 otherwise this call will return an error.
670 If the call is successful the function returns 0.
672 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
674 to get further details of the error.
675 zero — send write zeroes command to the NBD server
677 int nbd_zero (struct nbd_handle *h, uint64_t count, uint64_t offset, uint32_t flags);
678 Issue a write zeroes command to the NBD server, which if supported by
680 the server causes a zeroes to be written efficiently starting at
681 "offset" and ending at "offset" + "count" - 1. The call returns when
682 the command has been acknowledged by the server, or there is an error.
683 The "flags" parameter may be 0 for no flags, or may contain
685 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
686 the data has been committed to permanent storage (if that is supported
687 - some servers cannot do this, see "nbd_can_fua"), and/or
688 "LIBNBD_CMD_FLAG_NO_HOLE" meaning that the server should favor writing
689 actual allocated zeroes over punching a hole.
690 The handle must be connected and finished handshaking with the server,
692 otherwise this call will return an error.
693 If the call is successful the function returns 0.
695 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
697 to get further details of the error.
698 block_status — send block status command to the NBD server
700 int nbd_block_status (struct nbd_handle *h, uint64_t count, uint64_t offset, void *data, int (*extent) (void *data, const char *metacontext, uint64_t offset, uint32_t *entries, size_t nr_entries), uint32_t flags);
701 Issue the block status command to the NBD server. If supported by the
703 server, this causes metadata context information about blocks beginning
704 from the specified offset to be returned. The "count" parameter is a
705 hint: the server may choose to return less status, or the final block
706 may extend beyond the requested range. If multiple contexts are
707 supported, the number of blocks and cumulative length of those blocks
708 need not be identical between contexts.
709 Depending on which metadata contexts were enabled before connecting
711 (see "nbd_add_meta_context") and which are supported by the server (see
712 "nbd_can_meta_context") this call returns information about extents by
713 calling back to the extent function. The callback cannot call "nbd_*"
714 APIs on the same handle since it holds the handle lock and will cause a
715 deadlock. If the callback returns "-1", any remaining contexts will be
716 ignored and the overall block status command will fail with the same
717 value of "errno" left after the failing callback.
718 The extent function is called once per type of metadata available. The
720 "metacontext" parameter is a string such as "base:allocation". The
721 "entries" array is an array of pairs of integers with the first entry
722 in each pair being the length (in bytes) of the block and the second
723 entry being a status/flags field which is specific to the metadata
724 context. (The number of pairs passed to the function is
725 "nr_entries/2".) The NBD protocol document in the section about
726 "NBD_REPLY_TYPE_BLOCK_STATUS" describes the meaning of this array.
727 It is possible for the extent function to be called more times than you
729 expect (if the server is buggy), so always check the "metacontext"
730 field to ensure you are receiving the data you expect. It is also
731 possible that the extent function is not called at all, even for
732 metadata contexts that you requested. This indicates either that the
733 server doesn't support the context or for some other reason cannot
734 return the data.
735 The "flags" parameter may be 0 for no flags, or may contain
737 "LIBNBD_CMD_FLAG_REQ_ONE" meaning that the server should return only
738 one extent per metadata context where that extent does not exceed
739 "count" bytes; however, libnbd does not validate that the server obeyed
740 the flag.
741 The handle must be connected and finished handshaking with the server,
743 otherwise this call will return an error.
744 If the call is successful the function returns 0.
746 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
748 to get further details of the error.
749 poll — poll the handle once
751 int nbd_poll (struct nbd_handle *h, int timeout);
752 This is a simple implementation of poll(2) which is used internally by
754 synchronous API calls. It is mainly useful as an example of how you
755 might integrate libnbd with your own main loop, rather than being
756 intended as something you would use.
757 If the call is successful the function returns 0.
759 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
761 to get further details of the error.
762 aio_connect — connect to the NBD server
764 int nbd_aio_connect (struct nbd_handle *h, const struct sockaddr *addr, socklen_t addrlen);
765 Begin connecting to the NBD server. Parameters behave as documented in
767 "nbd_connect".
768 You can check if the connection is still connecting by calling
770 "nbd_aio_is_connecting", or if it has connected to the server and
771 completed the NBD handshake by calling "nbd_aio_is_ready", on the
772 connection.
773 The handle must be newly created, otherwise this call will return an
775 error.
776 If the call is successful the function returns 0.
778 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
780 to get further details of the error.
781 aio_connect_uri — connect to an NBD URI
783 int nbd_aio_connect_uri (struct nbd_handle *h, const char *uri);
784 Begin connecting to the NBD URI "uri". Parameters behave as documented
786 in "nbd_connect_uri".
787 You can check if the connection is still connecting by calling
789 "nbd_aio_is_connecting", or if it has connected to the server and
790 completed the NBD handshake by calling "nbd_aio_is_ready", on the
791 connection.
792 This call will fail if libnbd was not compiled with libxml2; you can
794 test whether this is the case with "nbd_supports_uri". Support for
795 URIs that require TLS will fail if libnbd was not compiled with gnutls;
796 you can test whether this is the case with "nbd_supports_tls".
797 The handle must be newly created, otherwise this call will return an
799 error.
800 If the call is successful the function returns 0.
802 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
804 to get further details of the error.
805 aio_connect_unix — connect to the NBD server over a Unix domain socket
807 int nbd_aio_connect_unix (struct nbd_handle *h, const char *unixsocket);
808 Begin connecting to the NBD server over Unix domain socket
810 ("unixsocket"). Parameters behave as documented in "nbd_connect_unix".
811 You can check if the connection is still connecting by calling
813 "nbd_aio_is_connecting", or if it has connected to the server and
814 completed the NBD handshake by calling "nbd_aio_is_ready", on the
815 connection.
816 The handle must be newly created, otherwise this call will return an
818 error.
819 If the call is successful the function returns 0.
821 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
823 to get further details of the error.
824 aio_connect_tcp — connect to the NBD server over a TCP port
826 int nbd_aio_connect_tcp (struct nbd_handle *h, const char *hostname, const char *port);
827 Begin connecting to the NBD server listening on "hostname:port".
829 Parameters behave as documented in "nbd_connect_tcp".
830 You can check if the connection is still connecting by calling
832 "nbd_aio_is_connecting", or if it has connected to the server and
833 completed the NBD handshake by calling "nbd_aio_is_ready", on the
834 connection.
835 The handle must be newly created, otherwise this call will return an
837 error.
838 If the call is successful the function returns 0.
840 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
842 to get further details of the error.
843 aio_connect_command — connect to the NBD server
845 int nbd_aio_connect_command (struct nbd_handle *h, char **argv);
846 Run the command as a subprocess and begin connecting to it over
848 stdin/stdout. Parameters behave as documented in
849 "nbd_connect_command".
850 You can check if the connection is still connecting by calling
852 "nbd_aio_is_connecting", or if it has connected to the server and
853 completed the NBD handshake by calling "nbd_aio_is_ready", on the
854 connection.
855 The handle must be newly created, otherwise this call will return an
857 error.
858 If the call is successful the function returns 0.
860 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
862 to get further details of the error.
863 aio_pread — read from the NBD server
865 int64_t nbd_aio_pread (struct nbd_handle *h, void *buf, size_t count, uint64_t offset, uint32_t flags);
866 Issue a read command to the NBD server. This returns the unique
868 positive 64 bit handle for this command, or "-1" on error. To check if
869 the command completed, call "nbd_aio_command_completed". Note that you
870 must ensure "buf" is valid until the command has completed. Other
871 parameters behave as documented in "nbd_pread".
872 The handle must be connected and finished handshaking with the server,
874 otherwise this call will return an error.
875 This call returns a 64 bit signed integer ≥ 0.
877 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
879 to get further details of the error.
880 aio_pwrite — write to the NBD server
882 int64_t nbd_aio_pwrite (struct nbd_handle *h, const void *buf, size_t count, uint64_t offset, uint32_t flags);
883 Issue a write command to the NBD server. This returns the unique
885 positive 64 bit handle for this command, or "-1" on error. To check if
886 the command completed, call "nbd_aio_command_completed". Note that you
887 must ensure "buf" is valid until the command has completed. Other
888 parameters behave as documented in "nbd_pwrite".
889 The handle must be connected and finished handshaking with the server,
891 otherwise this call will return an error.
892 This call returns a 64 bit signed integer ≥ 0.
894 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
896 to get further details of the error.
897 aio_disconnect — disconnect from the NBD server
899 int nbd_aio_disconnect (struct nbd_handle *h, uint32_t flags);
900 Issue the disconnect command to the NBD server. This is not a normal
902 command because NBD servers are not obliged to send a reply. Instead
903 you should wait for "nbd_aio_is_closed" to become true on the
904 connection.
905 The "flags" parameter must be 0 for now (it exists for future NBD
907 protocol extensions). There is no direct synchronous counterpart;
908 however, "nbd_shutdown" will call this function if appropriate.
909 The handle must be connected and finished handshaking with the server,
911 otherwise this call will return an error.
912 If the call is successful the function returns 0.
914 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
916 to get further details of the error.
917 aio_flush — send flush command to the NBD server
919 int64_t nbd_aio_flush (struct nbd_handle *h, uint32_t flags);
920 Issue the flush command to the NBD server. This returns the unique
922 positive 64 bit handle for this command, or "-1" on error. To check if
923 the command completed, call "nbd_aio_command_completed". Parameters
924 behave as documented in "nbd_flush".
925 The handle must be connected and finished handshaking with the server,
927 otherwise this call will return an error.
928 This call returns a 64 bit signed integer ≥ 0.
930 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
932 to get further details of the error.
933 aio_trim — send trim command to the NBD server
935 int64_t nbd_aio_trim (struct nbd_handle *h, uint64_t count, uint64_t offset, uint32_t flags);
936 Issue a trim command to the NBD server. This returns the unique
938 positive 64 bit handle for this command, or "-1" on error. To check if
939 the command completed, call "nbd_aio_command_completed". Parameters
940 behave as documented in "nbd_trim".
941 The handle must be connected and finished handshaking with the server,
943 otherwise this call will return an error.
944 This call returns a 64 bit signed integer ≥ 0.
946 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
948 to get further details of the error.
949 aio_cache — send cache (prefetch) command to the NBD server
951 int64_t nbd_aio_cache (struct nbd_handle *h, uint64_t count, uint64_t offset, uint32_t flags);
952 Issue the cache (prefetch) command to the NBD server. This returns the
954 unique positive 64 bit handle for this command, or "-1" on error. To
955 check if the command completed, call "nbd_aio_command_completed".
956 Parameters behave as documented in "nbd_cache".
957 The handle must be connected and finished handshaking with the server,
959 otherwise this call will return an error.
960 This call returns a 64 bit signed integer ≥ 0.
962 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
964 to get further details of the error.
965 aio_zero — send write zeroes command to the NBD server
967 int64_t nbd_aio_zero (struct nbd_handle *h, uint64_t count, uint64_t offset, uint32_t flags);
968 Issue a write zeroes command to the NBD server. This returns the
970 unique positive 64 bit handle for this command, or "-1" on error. To
971 check if the command completed, call "nbd_aio_command_completed".
972 Parameters behave as documented in "nbd_zero".
973 The handle must be connected and finished handshaking with the server,
975 otherwise this call will return an error.
976 This call returns a 64 bit signed integer ≥ 0.
978 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
980 to get further details of the error.
981 aio_block_status — send block status command to the NBD server
983 int64_t nbd_aio_block_status (struct nbd_handle *h, uint64_t count, uint64_t offset, void *data, int (*extent) (void *data, const char *metacontext, uint64_t offset, uint32_t *entries, size_t nr_entries), uint32_t flags);
984 Send the block status command to the NBD server. This returns the
986 unique positive 64 bit handle for this command, or "-1" on error. To
987 check if the command completed, call "nbd_aio_command_completed".
988 Parameters behave as documented in "nbd_block_status".
989 The handle must be connected and finished handshaking with the server,
991 otherwise this call will return an error.
992 This call returns a 64 bit signed integer ≥ 0.
994 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
996 to get further details of the error.
997 aio_get_fd — return file descriptor associated with this connection
999 int nbd_aio_get_fd (struct nbd_handle *h);
1000 Return the underlying file descriptor associated with this connection.
1002 You can use this to check if the file descriptor is ready for reading
1003 or writing and call "nbd_aio_notify_read" or "nbd_aio_notify_write".
1004 See also "nbd_aio_get_direction". Do not do anything else with the
1005 file descriptor.
1006 This call returns a file descriptor.
1008 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
1010 to get further details of the error.
1011 aio_get_direction — return the read or write direction
1013 int nbd_aio_get_direction (struct nbd_handle *h);
1014 Return the current direction of this connection, which means whether we
1016 are next expecting to read data from the server, write data to the
1017 server, or both. It returns
1018 "LIBNBD_AIO_DIRECTION_READ" = 1
1020 We are expected next to read from the server. If using poll(2) you
1021 would set "events = POLLIN". If "revents" returns "POLLIN" you
1022 would then call "nbd_aio_notify_read".
1023 "LIBNBD_AIO_DIRECTION_WRITE" = 2
1025 We are expected next to write to the server. If using poll(2) you
1026 would set "events = POLLOUT". If "revents" returns "POLLOUT" you
1027 would then call "nbd_aio_notify_write".
1028 "LIBNBD_AIO_DIRECTION_BOTH" = 3
1030 We are expected next to either read or write to the server. If
1031 using poll(2) you would set "events = POLLIN|POLLOUT". If one of
1032 "POLLIN" or "POLLOUT" is returned, then see above. However note
1033 that you shouldn't call "nbd_aio_notify_read" and
1034 "nbd_aio_notify_write" because calling the first one will change
1035 the state of the connection, possibly invalidating the second
1036 notification.
1037 This call returns an integer ≥ 0.
1039 This function does not fail.
1041 aio_notify_read — notify that the connection is readable
1043 int nbd_aio_notify_read (struct nbd_handle *h);
1044 Send notification to the state machine that the connection is readable.
1046 Typically this is called after your main loop has detected that the
1047 file descriptor associated with this connection is readable.
1048 If the call is successful the function returns 0.
1050 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
1052 to get further details of the error.
1053 aio_notify_write — notify that the connection is writable
1055 int nbd_aio_notify_write (struct nbd_handle *h);
1056 Send notification to the state machine that the connection is writable.
1058 Typically this is called after your main loop has detected that the
1059 file descriptor associated with this connection is writable.
1060 If the call is successful the function returns 0.
1062 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
1064 to get further details of the error.
1065 aio_is_created — check if the connection has just been created
1067 int nbd_aio_is_created (struct nbd_handle *h);
1068 Return true if this connection has just been created. This is the
1070 state before the handle has started connecting to a server. In this
1071 state the handle can start to be connected by calling functions such as
1072 "nbd_aio_connect".
1073 This call returns a boolean value.
1075 This function does not fail.
1077 aio_is_connecting — check if the connection is connecting or handshaking
1079 int nbd_aio_is_connecting (struct nbd_handle *h);
1080 Return true if this connection is connecting to the server or in the
1082 process of handshaking and negotiating options which happens before the
1083 handle becomes ready to issue commands (see "nbd_aio_is_ready").
1084 This call returns a boolean value.
1086 This function does not fail.
1088 aio_is_ready — check if the connection is in the ready state
1090 int nbd_aio_is_ready (struct nbd_handle *h);
1091 Return true if this connection is connected to the NBD server, the
1093 handshake has completed, and the connection is idle or waiting for a
1094 reply. In this state the handle is ready to issue commands.
1095 This call returns a boolean value.
1097 This function does not fail.
1099 aio_is_processing — check if the connection is processing a command
1101 int nbd_aio_is_processing (struct nbd_handle *h);
1102 Return true if this connection is connected to the NBD server, the
1104 handshake has completed, and the connection is processing commands
1105 (either writing out a request or reading a reply).
1106 Note the ready state ("nbd_aio_is_ready") is not included. In the
1108 ready state commands may be in flight (the server is processing them),
1109 but libnbd is not processing them.
1110 This call returns a boolean value.
1112 This function does not fail.
1114 aio_is_dead — check if the connection is dead
1116 int nbd_aio_is_dead (struct nbd_handle *h);
1117 Return true if the connection has encountered a fatal error and is
1119 dead. In this state the handle may only be closed. There is no way to
1120 recover a handle from the dead state.
1121 This call returns a boolean value.
1123 This function does not fail.
1125 aio_is_closed — check if the connection is closed
1127 int nbd_aio_is_closed (struct nbd_handle *h);
1128 Return true if the connection has closed. There is no way to reconnect
1130 a closed connection. Instead you must close the whole handle.
1131 This call returns a boolean value.
1133 This function does not fail.
1135 aio_command_completed — check if the command completed
1137 int nbd_aio_command_completed (struct nbd_handle *h, int64_t handle);
1138 Return true if the command completed. If this function returns true
1140 then the command was successful and it has been retired. Return false
1141 if the command is still in flight. This can also fail with an error in
1142 case the command failed (in this case the command is also retired).
1143 The "handle" parameter is the positive unique 64 bit handle for the
1145 command, as returned by a call such as "nbd_aio_pread".
1146 This call returns a boolean value.
1148 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
1150 to get further details of the error.
1151 aio_peek_command_completed — check if any command has completed
1153 int64_t nbd_aio_peek_command_completed (struct nbd_handle *h);
1154 Return the unique positive 64 bit handle of the first non-retired but
1156 completed command, 0 if no command is awaiting retirement, or "-1" on
1157 error. Any handle returned by this function must still be passed to
1158 "aio_command_completed" to actually retire the command and learn
1159 whether the command was successful.
1160 This call returns a 64 bit signed integer ≥ 0.
1162 On error "-1" is returned. See "ERROR HANDLING" in libnbd(3) for how
1164 to get further details of the error.
1165 connection_state — return a descriptive string for the state of the
1167 connection
1168 const char *nbd_connection_state (struct nbd_handle *h);
1169 Returns a descriptive string for the state of the connection. This can
1171 be used for debugging or troubleshooting, but you should not rely on
1172 the state of connections since it may change in future versions.
1173 This call returns a statically allocated string. You must not try to
1175 free the string.
1176 On error "NULL" is returned. See "ERROR HANDLING" in libnbd(3) for how
1178 to get further details of the error.
1179 get_package_name — return the name of the library
1181 const char *nbd_get_package_name (struct nbd_handle *h);
1182 Returns the name of the library, always "libnbd" unless the library was
1184 modified with another name at compile time.
1185 This call returns a statically allocated string. You must not try to
1187 free the string.
1188 This function does not fail.
1190 get_version — return a descriptive string for the state of the connection
1192 const char *nbd_get_version (struct nbd_handle *h);
1193 Return the version of libnbd. This is returned as a string in the form
1195 "major.minor.release" where each of major, minor and release is a small
1196 positive integer. For example "1.0.3".
1197 The major number is 0 for the early experimental versions of libnbd
1199 where we still had an unstable API, or 1 for the versions of libnbd
1200 with a long-term stable API and ABI.
1201 The minor number is even (0, 2, etc) for stable releases, and odd (1,
1203 3, etc) for development versions. Note that new APIs added in a
1204 development version remain experimental and subject to change in that
1205 branch until they appear in a stable release.
1206 The release number is incremented for each release along a particular
1208 branch.
1209 This call returns a statically allocated string. You must not try to
1211 free the string.
1212 This function does not fail.
1214 supports_tls — return true if libnbd was compiled with support for TLS
1216 int nbd_supports_tls (struct nbd_handle *h);
1217 Returns true if libnbd was compiled with gnutls which is required to
1219 support TLS encryption, or false if not. See "nbd_set_tls".
1220 This call returns a boolean value.
1222 This function does not fail.
1224 supports_uri — return true if libnbd was compiled with support for NBD URIs
1226 int nbd_supports_uri (struct nbd_handle *h);
1227 Returns true if libnbd was compiled with libxml2 which is required to
1229 support NBD URIs, or false if not. See "nbd_connect_uri" and
1230 "nbd_aio_connect_uri".
1231 This call returns a boolean value.
1233 This function does not fail.
1235
1237 libnbd(3).
1238
1240 Eric Blake
1241 Richard W.M. Jones
1243
1245 Copyright (C) 2019 Red Hat Inc.
1246
1248 This library is free software; you can redistribute it and/or modify it
1249 under the terms of the GNU Lesser General Public License as published
1250 by the Free Software Foundation; either version 2 of the License, or
1251 (at your option) any later version.
1252 This library is distributed in the hope that it will be useful, but
1254 WITHOUT ANY WARRANTY; without even the implied warranty of
1255 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1256 Lesser General Public License for more details.
1257 You should have received a copy of the GNU Lesser General Public
1259 License along with this library; if not, write to the Free Software
1260 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
1261 02110-1301 USA
1262libnbd-0.1.4 2019-06-09 libnbd-api(3)