1NBD(3) NBD(3)
2
6 NBD - OCaml bindings for libnbd.
7
9 Module NBD
10
12 Module NBD
13 : sig end
14 OCaml bindings for libnbd.
17 For full documentation see libnbd-ocaml(3) and libnbd(3).
19 For examples written in OCaml see the libnbd source code ocaml/examples
21 subdirectory.
22 exception Error of string * int
29 Exception thrown when an API call fails.
32 The string is the error message, and the int is the raw errno (if
34 available).
35 exception Closed of string
39 Exception thrown if you call a closed handle.
42 type cookie = int64
45 module TLS : sig end
50 module SIZE : sig end
55 module CMD_FLAG : sig end
60 module HANDSHAKE_FLAG : sig end
65 module STRICT : sig end
70 module ALLOW_TRANSPORT : sig end
75 module SHUTDOWN : sig end
80 val aio_direction_read : int32
86 val aio_direction_write : int32
91 val aio_direction_both : int32
96 val read_data : int32
101 val read_hole : int32
106 val read_error : int32
111 val namespace_base : string
116 val context_base_allocation : string
121 val state_hole : int32
126 val state_zero : int32
131 module Buffer : sig end
135 Persistent buffer used in AIO calls.
138 type t
141 The handle.
144 val create : unit -> t
148 Create a new handle.
150 val close : t -> unit
154 Close a handle.
156 Handles can also be closed by the garbage collector when they become
158 unreachable. This call is used only if you want to force the handle to
159 close now and reclaim resources immediately.
160 val set_debug : t -> bool -> unit
164 set or clear the debug flag
166 Set or clear the debug flag. When debugging is enabled, debugging mes‐
168 sages from the library are printed to stderr, unless a debugging call‐
169 back has been defined too (see nbd_set_debug_callback(3)) in which case
170 they are sent to that function. This flag defaults to false on newly
171 created handles, except if "LIBNBD_DEBUG=1" is set in the environment
172 in which case it defaults to true.
173 val get_debug : t -> bool
177 return the state of the debug flag
179 Return the state of the debug flag on this handle.
181 val set_debug_callback : t -> (string -> string -> int) -> unit
185 set the debug callback
187 Set the debug callback. This function is called when the library emits
189 debug messages, when debugging is enabled on a handle. The callback
190 parameters are "user_data" passed to this function, the name of the
191 libnbd function emitting the debug message ("context"), and the message
192 itself ("msg"). If no debug callback is set on a handle then messages
193 are printed on "stderr".
194 The callback should not call "nbd_*" APIs on the same handle since it
196 can be called while holding the handle lock and will cause a deadlock.
197 val clear_debug_callback : t -> unit
201 clear the debug callback
203 Remove the debug callback if one was previously associated with the
205 handle (with nbd_set_debug_callback(3)). If no callback was associated
206 this does nothing.
207 val set_handle_name : t -> string -> unit
211 set the handle name
213 Handles have a name which is unique within the current process. The
215 handle name is used in debug output.
216 Handle names are normally generated automatically and have the form
218 "nbd1", "nbd2", etc., but you can optionally use this call to give the
219 handles a name which is meaningful for your application to make debug‐
220 ging output easier to understand.
221 val get_handle_name : t -> string
225 get the handle name
227 Get the name of the handle. If it was previously set by calling
229 nbd_set_handle_name(3) then this returns the name that was set. Other‐
230 wise it will return a generic name like "nbd1", "nbd2", etc.
231 val set_export_name : t -> string -> unit
235 set the export name
237 For servers which require an export name or can serve different content
239 on different exports, set the "export_name" to connect to. The default
240 is the empty string "".
241 This is only relevant when connecting to servers using the newstyle
243 protocol as the oldstyle protocol did not support export names. The NBD
244 protocol limits export names to 4096 bytes, but servers may not support
245 the full length. The encoding of export names is always UTF-8.
246 When option mode is not in use, the export name must be set before
248 beginning a connection. However, when nbd_set_opt_mode(3) has enabled
249 option mode, it is possible to change the export name prior to
250 nbd_opt_go(3). In particular, the use of nbd_opt_list(3) during negoti‐
251 ation can be used to determine a name the server is likely to accept,
252 and nbd_opt_info(3) can be used to learn details about an export before
253 connecting.
254 This call may be skipped if using nbd_connect_uri(3) to connect to a
256 URI that includes an export name.
257 val get_export_name : t -> string
261 get the export name
263 Get the export name associated with the handle. This is the name that
265 libnbd requests; see nbd_get_canonical_export_name(3) for determining
266 if the server has a different canonical name for the given export (most
267 common when requesting the default export name of an empty string "")
268 val set_full_info : t -> bool -> unit
272 control whether NBD_OPT_GO requests extra details
274 By default, when connecting to an export, libnbd only requests the
276 details it needs to service data operations. The NBD protocol says that
277 a server can supply optional information, such as a canonical name of
278 the export (see nbd_get_canonical_export_name(3)) or a description of
279 the export (see nbd_get_export_description(3)), but that a hint from
280 the client makes it more likely for this extra information to be pro‐
281 vided. This function controls whether libnbd will provide that hint.
282 Note that even when full info is requested, the server is not obligated
284 to reply with all information that libnbd requested. Similarly, libnbd
285 will ignore any optional server information that libnbd has not yet
286 been taught to recognize.
287 val get_full_info : t -> bool
291 see if NBD_OPT_GO requests extra details
293 Return the state of the full info request flag on this handle.
295 val get_canonical_export_name : t -> string
299 return the canonical export name, if the server has one
301 The NBD protocol permits a server to report an optional canonical
303 export name, which may differ from the client's request (as set by
304 nbd_set_export_name(3) or nbd_connect_uri(3)). This function accesses
305 any name returned by the server; it may be the same as the client
306 request, but is more likely to differ when the client requested a con‐
307 nection to the default export name (an empty string "").
308 Some servers are unlikely to report a canonical name unless the client
310 specifically hinted about wanting it, via nbd_set_full_info(3).
311 val get_export_description : t -> string
315 return the export description, if the server has one
317 The NBD protocol permits a server to report an optional export descrip‐
319 tion. This function reports any description returned by the server.
320 Some servers are unlikely to report a description unless the client
322 specifically hinted about wanting it, via nbd_set_full_info(3). For
323 qemu-nbd(8), a description is set with *-D*.
324 val set_tls : t -> TLS.t -> unit
328 enable or require TLS (authentication and encryption)
330 Enable or require TLS (authenticated and encrypted connections) to the
332 NBD server. The possible settings are:
333 "LIBNBD_TLS_DISABLE" Disable TLS. (The default setting, unless using
335 nbd_connect_uri(3) with a URI that requires TLS)
336 "LIBNBD_TLS_ALLOW" Enable TLS if possible.
338 This option is insecure (or best effort) in that in some cases it will
340 fall back to an unencrypted and/or unauthenticated connection if TLS
341 could not be established. Use "LIBNBD_TLS_REQUIRE" below if the connec‐
342 tion must be encrypted.
343 Some servers will drop the connection if TLS fails so fallback may not
345 be possible.
346 "LIBNBD_TLS_REQUIRE" Require an encrypted and authenticated TLS connec‐
348 tion. Always fail to connect if the connection is not encrypted and
349 authenticated.
350 As well as calling this you may also need to supply the path to the
352 certificates directory (nbd_set_tls_certificates(3)), the username
353 (nbd_set_tls_username(3)) and/or the Pre-Shared Keys (PSK) file
354 (nbd_set_tls_psk_file(3)). For now, when using nbd_connect_uri(3), any
355 URI query parameters related to TLS are not handled automatically. Set‐
356 ting the level higher than zero will fail if libnbd was not compiled
357 against gnutls; you can test whether this is the case with nbd_sup‐
358 ports_tls(3).
359 val get_tls : t -> TLS.t
363 get the TLS request setting
365 Get the TLS request setting.
367 Note: If you want to find out if TLS was actually negotiated on a par‐
369 ticular connection use nbd_get_tls_negotiated(3) instead.
370 val get_tls_negotiated : t -> bool
374 find out if TLS was negotiated on a connection
376 After connecting you may call this to find out if the connection is
378 using TLS.
379 This is only really useful if you set the TLS request mode to
381 "LIBNBD_TLS_ALLOW" (see nbd_set_tls(3)), because in this mode we try to
382 use TLS but fall back to unencrypted if it was not available. This
383 function will tell you if TLS was negotiated or not.
384 In "LIBNBD_TLS_REQUIRE" mode (the most secure) the connection would
386 have failed if TLS could not be negotiated, and in "LIBNBD_TLS_DISABLE"
387 mode TLS is not tried.
388 val set_tls_certificates : t -> string -> unit
392 set the path to the TLS certificates directory
394 Set the path to the TLS certificates directory. If not set and TLS is
396 used then a compiled in default is used. For root this is
397 "/etc/pki/libnbd/". For non-root this is "$HOME/.pki/libnbd" and
398 "$HOME/.config/pki/libnbd". If none of these directories can be found
399 then the system trusted CAs are used.
400 This function may be called regardless of whether TLS is supported, but
402 will have no effect unless nbd_set_tls(3) is also used to request or
403 require TLS.
404 val set_tls_verify_peer : t -> bool -> unit
408 set whether we verify the identity of the server
410 Set this flag to control whether libnbd will verify the identity of the
412 server from the server's certificate and the certificate authority.
413 This defaults to true when connecting to TCP servers using TLS certifi‐
414 cate authentication, and false otherwise.
415 This function may be called regardless of whether TLS is supported, but
417 will have no effect unless nbd_set_tls(3) is also used to request or
418 require TLS.
419 val get_tls_verify_peer : t -> bool
423 get whether we verify the identity of the server
425 Get the verify peer flag.
427 val set_tls_username : t -> string -> unit
431 set the TLS username
433 Set the TLS client username. This is used if authenticating with PSK
435 over TLS is enabled. If not set then the local username is used.
436 This function may be called regardless of whether TLS is supported, but
438 will have no effect unless nbd_set_tls(3) is also used to request or
439 require TLS.
440 val get_tls_username : t -> string
444 get the current TLS username
446 Get the current TLS username.
448 val set_tls_psk_file : t -> string -> unit
452 set the TLS Pre-Shared Keys (PSK) filename
454 Set the TLS Pre-Shared Keys (PSK) filename. This is used if trying to
456 authenticate to the server using with a pre-shared key. There is no
457 default so if this is not set then PSK authentication cannot be used to
458 connect to the server.
459 This function may be called regardless of whether TLS is supported, but
461 will have no effect unless nbd_set_tls(3) is also used to request or
462 require TLS.
463 val set_request_structured_replies : t -> bool -> unit
467 control use of structured replies
469 By default, libnbd tries to negotiate structured replies with the
471 server, as this protocol extension must be in use before
472 nbd_can_meta_context(3) or nbd_can_df(3) can return true. However, for
473 integration testing, it can be useful to clear this flag rather than
474 find a way to alter the server to fail the negotiation request.
475 val get_request_structured_replies : t -> bool
479 see if structured replies are attempted
481 Return the state of the request structured replies flag on this handle.
483 Note: If you want to find out if structured replies were actually nego‐
485 tiated on a particular connection use nbd_get_structured_replies_nego‐
486 tiated(3) instead.
487 val get_structured_replies_negotiated : t -> bool
491 see if structured replies are in use
493 After connecting you may call this to find out if the connection is
495 using structured replies.
496 val set_handshake_flags : t -> HANDSHAKE_FLAG.t list -> unit
500 control use of handshake flags
502 By default, libnbd tries to negotiate all possible handshake flags that
504 are also supported by the server, since omitting a handshake flag can
505 prevent the use of other functionality such as TLS encryption or struc‐
506 tured replies. However, for integration testing, it can be useful to
507 reduce the set of flags supported by the client to test that a particu‐
508 lar server can handle various clients that were compliant to older ver‐
509 sions of the NBD specification.
510 The "flags" argument is a bitmask, including zero or more of the fol‐
512 lowing handshake flags:
513 "LIBNBD_HANDSHAKE_FLAG_FIXED_NEWSTYLE" = 1 The server gracefully han‐
515 dles unknown option requests from the client, rather than disconnect‐
516 ing. Without this flag, a client cannot safely request to use exten‐
517 sions such as TLS encryption or structured replies, as the request may
518 cause an older server to drop the connection.
519 "LIBNBD_HANDSHAKE_FLAG_NO_ZEROES" = 2 If the client is forced to use
521 "NBD_OPT_EXPORT_NAME" instead of the preferred "NBD_OPT_GO", this flag
522 allows the server to send fewer all-zero padding bytes over the connec‐
523 tion.
524 For convenience, the constant "LIBNBD_HANDSHAKE_FLAG_MASK" is available
526 to describe all flags supported by this build of libnbd. Future NBD
527 extensions may add further flags, which in turn may be enabled by
528 default in newer libnbd. As such, when attempting to disable only one
529 specific bit, it is wiser to first call nbd_get_handshake_flags(3) and
530 modify that value, rather than blindly setting a constant value.
531 val get_handshake_flags : t -> HANDSHAKE_FLAG.t list
535 see which handshake flags are supported
537 Return the state of the handshake flags on this handle. When the han‐
539 dle has not yet completed a connection (see nbd_aio_is_created(3)),
540 this returns the flags that the client is willing to use, provided the
541 server also advertises those flags. After the connection is ready (see
542 nbd_aio_is_ready(3)), this returns the flags that were actually agreed
543 on between the server and client. If the NBD protocol defines new
544 handshake flags, then the return value from a newer library version may
545 include bits that were undefined at the time of compilation.
546 val set_strict_mode : t -> STRICT.t list -> unit
550 control how strictly to follow NBD protocol
552 By default, libnbd tries to detect requests that would trigger unde‐
554 fined behavior in the NBD protocol, and rejects them client side with‐
555 out causing any network traffic, rather than risking undefined server
556 behavior. However, for integration testing, it can be handy to relax
557 the strictness of libnbd, to coerce it into sending such requests over
558 the network for testing the robustness of the server in dealing with
559 such traffic.
560 The "flags" argument is a bitmask, including zero or more of the fol‐
562 lowing strictness flags:
563 "LIBNBD_STRICT_COMMANDS" = 1 If set, this flag rejects client requests
565 that do not comply with the set of advertised server flags (for exam‐
566 ple, attempting a write on a read-only server, or attempting to use
567 "LIBNBD_CMD_FLAG_FUA" when nbd_can_fua(3) returned false). If clear,
568 this flag relies on the server to reject unexpected commands.
569 "LIBNBD_STRICT_FLAGS" = 2 If set, this flag rejects client requests
571 that attempt to set a command flag not recognized by libnbd (those out‐
572 side of "LIBNBD_CMD_FLAG_MASK"), or a flag not normally associated with
573 a command (such as using "LIBNBD_CMD_FLAG_FUA" on a read command). If
574 clear, all flags are sent on to the server, even if sending such a flag
575 may cause the server to change its reply in a manner that confuses
576 libnbd, perhaps causing deadlock or ending the connection.
577 Flags that are known by libnbd as associated with a given command (such
579 as "LIBNBD_CMD_FLAG_DF" for nbd_pread_structured(3) gated by
580 nbd_can_df(3)) are controlled by "LIBNBD_STRICT_COMMANDS" instead.
581 Note that the NBD protocol only supports 16 bits of command flags, even
583 though the libnbd API uses "uint32_t"; bits outside of the range per‐
584 mitted by the protocol are always a client-side error.
585 "LIBNBD_STRICT_BOUNDS" = 3 If set, this flag rejects client requests
587 that would exceed the export bounds without sending any traffic to the
588 server. If clear, this flag relies on the server to detect
589 out-of-bounds requests.
590 "LIBNBD_STRICT_ZERO_SIZE" = 4 If set, this flag rejects client requests
592 with length 0. If clear, this permits zero-length requests to the
593 server, which may produce undefined results.
594 "LIBNBD_STRICT_ALIGN" = 5 If set, and the server provided minimum block
596 sizes (see nbd_get_block_size(3), this flag rejects client requests
597 that do not have length and offset aligned to the server's minimum
598 requirements. If clear, unaligned requests are sent to the server,
599 where it is up to the server whether to honor or reject the request.
600 For convenience, the constant "LIBNBD_STRICT_MASK" is available to
602 describe all strictness flags supported by this build of libnbd. Future
603 versions of libnbd may add further flags, which are likely to be
604 enabled by default for additional client-side filtering. As such, when
605 attempting to relax only one specific bit while keeping remaining
606 checks at the client side, it is wiser to first call
607 nbd_get_strict_mode(3) and modify that value, rather than blindly set‐
608 ting a constant value.
609 val get_strict_mode : t -> STRICT.t list
613 see which strictness flags are in effect
615 Return flags indicating which protocol strictness items are being
617 enforced locally by libnbd rather than the server. The return value
618 from a newer library version may include bits that were undefined at
619 the time of compilation.
620 val set_opt_mode : t -> bool -> unit
624 control option mode, for pausing during option negotiation
626 Set this flag to true in order to request that a connection command
628 "nbd_connect_*" will pause for negotiation options rather than proceed‐
629 ing all the way to the ready state, when communicating with a newstyle
630 server. This setting has no effect when connecting to an oldstyle
631 server.
632 When option mode is enabled, you have fine-grained control over which
634 options are negotiated, compared to the default of the server negotiat‐
635 ing everything on your behalf using settings made before starting the
636 connection. To leave the mode and proceed on to the ready state, you
637 must use nbd_opt_go(3) successfully; a failed nbd_opt_go(3) returns to
638 the negotiating state to allow a change of export name before trying
639 again. You may also use nbd_opt_abort(3) to end the connection without
640 finishing negotiation.
641 val get_opt_mode : t -> bool
645 return whether option mode was enabled
647 Return true if option negotiation mode was enabled on this handle.
649 val opt_go : t -> unit
653 end negotiation and move on to using an export
655 Request that the server finish negotiation and move on to serving the
657 export previously specified by the most recent nbd_set_export_name(3)
658 or nbd_connect_uri(3). This can only be used if nbd_set_opt_mode(3)
659 enabled option mode.
660 If this fails, the server may still be in negotiation, where it is pos‐
662 sible to attempt another option such as a different export name;
663 although older servers will instead have killed the connection.
664 val opt_abort : t -> unit
668 end negotiation and close the connection
670 Request that the server finish negotiation, gracefully if possible,
672 then close the connection. This can only be used if nbd_set_opt_mode(3)
673 enabled option mode.
674 val opt_list : t -> (string -> string -> int) -> int
678 request the server to list all exports during negotiation
680 Request that the server list all exports that it supports. This can
682 only be used if nbd_set_opt_mode(3) enabled option mode.
683 The "list" function is called once per advertised export, with any
685 "user_data" passed to this function, and with "name" and "description"
686 supplied by the server. Many servers omit descriptions, in which case
687 "description" will be an empty string. Remember that it is not safe to
688 call nbd_set_export_name(3) from within the context of the callback
689 function; rather, your code must copy any "name" needed for later use
690 after this function completes. At present, the return value of the
691 callback is ignored, although a return of -1 should be avoided.
692 For convenience, when this function succeeds, it returns the number of
694 exports that were advertised by the server.
695 Not all servers understand this request, and even when it is under‐
697 stood, the server might intentionally send an empty list to avoid being
698 an information leak, may encounter a failure after delivering partial
699 results, or may refuse to answer more than one query per connection in
700 the interest of avoiding negotiation that does not resolve. Thus, this
701 function may succeed even when no exports are reported, or may fail but
702 have a non-empty list. Likewise, the NBD protocol does not specify an
703 upper bound for the number of exports that might be advertised, so
704 client code should be aware that a server may send a lengthy list.
705 For nbd-server(1) you will need to allow clients to make list requests
707 by adding "allowlist=true" to the " generic " section of
708 /etc/nbd-server/config. For qemu-nbd(8), a description is set with
709 *-D*.
710 val opt_info : t -> unit
714 request the server for information about an export
716 Request that the server supply information about the export name previ‐
718 ously specified by the most recent nbd_set_export_name(3) or nbd_con‐
719 nect_uri(3). This can only be used if nbd_set_opt_mode(3) enabled
720 option mode.
721 If successful, functions like nbd_is_read_only(3) and nbd_get_size(3)
723 will report details about that export. In general, if nbd_opt_go(3) is
724 called next, that call will likely succeed with the details remaining
725 the same, although this is not guaranteed by all servers.
726 Not all servers understand this request, and even when it is under‐
728 stood, the server might fail the request even when a corresponding
729 nbd_opt_go(3) would succeed.
730 val opt_list_meta_context : t -> (string -> int) -> int
734 request the server to list available meta contexts
736 Request that the server list available meta contexts associated with
738 the export previously specified by the most recent
739 nbd_set_export_name(3) or nbd_connect_uri(3). This can only be used if
740 nbd_set_opt_mode(3) enabled option mode.
741 The NBD protocol allows a client to decide how many queries to ask the
743 server. Rather than taking that list of queries as a parameter to this
744 function, libnbd reuses the current list of requested meta contexts as
745 set by nbd_add_meta_context(3); you can use nbd_clear_meta_contexts(3)
746 to set up a different list of queries. When the list is empty, a server
747 will typically reply with all contexts that it supports; when the list
748 is non-empty, the server will reply only with supported contexts that
749 match the client's request. Note that a reply by the server might be
750 encoded to represent several feasible contexts within one string,
751 rather than multiple strings per actual context name that would actu‐
752 ally succeed during nbd_opt_go(3); so it is still necessary to use
753 nbd_can_meta_context(3) after connecting to see which contexts are
754 actually supported.
755 The "context" function is called once per server reply, with any
757 "user_data" passed to this function, and with "name" supplied by the
758 server. Remember that it is not safe to call nbd_add_meta_context(3)
759 from within the context of the callback function; rather, your code
760 must copy any "name" needed for later use after this function com‐
761 pletes. At present, the return value of the callback is ignored,
762 although a return of -1 should be avoided.
763 For convenience, when this function succeeds, it returns the number of
765 replies returned by the server.
766 Not all servers understand this request, and even when it is under‐
768 stood, the server might intentionally send an empty list because it
769 does not support the requested context, or may encounter a failure
770 after delivering partial results. Thus, this function may succeed even
771 when no contexts are reported, or may fail but have a non-empty list.
772 Likewise, the NBD protocol does not specify an upper bound for the num‐
773 ber of replies that might be advertised, so client code should be aware
774 that a server may send a lengthy list.
775 val add_meta_context : t -> string -> unit
779 ask server to negotiate metadata context
781 During connection libnbd can negotiate zero or more metadata contexts
783 with the server. Metadata contexts are features (such as "base:alloca‐
784 tion") which describe information returned by the nbd_block_status(3)
785 command (for "base:allocation" this is whether blocks of data are allo‐
786 cated, zero or sparse).
787 This call adds one metadata context to the list to be negotiated. You
789 can call it as many times as needed. The list is initially empty when
790 the handle is created; you can check the contents of the list with
791 nbd_get_nr_meta_contexts(3) and nbd_get_meta_context(3), or clear it
792 with nbd_clear_meta_contexts(3).
793 The NBD protocol limits meta context names to 4096 bytes, but servers
795 may not support the full length. The encoding of meta context names is
796 always UTF-8.
797 Not all servers support all metadata contexts. To learn if a context
799 was actually negotiated, call nbd_can_meta_context(3) after connecting.
800 The single parameter is the name of the metadata context, for example
802 "LIBNBD_CONTEXT_BASE_ALLOCATION". <libnbd.h> includes defined con‐
803 stants beginning with "LIBNBD_CONTEXT_" for some well-known contexts,
804 but you are free to pass in other contexts.
805 Other metadata contexts are server-specific, but include
807 "qemu:dirty-bitmap:..." and "qemu:allocation-depth" for qemu-nbd (see
808 qemu-nbd *-B* and *-A* options).
809 val get_nr_meta_contexts : t -> int
813 return the current number of requested meta contexts
815 During connection libnbd can negotiate zero or more metadata contexts
817 with the server. Metadata contexts are features (such as "base:alloca‐
818 tion") which describe information returned by the nbd_block_status(3)
819 command (for "base:allocation" this is whether blocks of data are allo‐
820 cated, zero or sparse).
821 This command returns how many meta contexts have been added to the list
823 to request from the server via nbd_add_meta_context(3). The server is
824 not obligated to honor all of the requests; to see what it actually
825 supports, see nbd_can_meta_context(3).
826 val get_meta_context : t -> int -> string
830 return the i'th meta context request
832 During connection libnbd can negotiate zero or more metadata contexts
834 with the server. Metadata contexts are features (such as "base:alloca‐
835 tion") which describe information returned by the nbd_block_status(3)
836 command (for "base:allocation" this is whether blocks of data are allo‐
837 cated, zero or sparse).
838 This command returns the i'th meta context request, as added by
840 nbd_add_meta_context(3), and bounded by nbd_get_nr_meta_contexts(3).
841 val clear_meta_contexts : t -> unit
845 reset the list of requested meta contexts
847 During connection libnbd can negotiate zero or more metadata contexts
849 with the server. Metadata contexts are features (such as "base:alloca‐
850 tion") which describe information returned by the nbd_block_status(3)
851 command (for "base:allocation" this is whether blocks of data are allo‐
852 cated, zero or sparse).
853 This command resets the list of meta contexts to request back to an
855 empty list, for re-population by further use of nbd_add_meta_con‐
856 text(3). It is primarily useful when option negotiation mode is
857 selected (see nbd_set_opt_mode(3)), for altering the list of attempted
858 contexts between subsequent export queries.
859 val set_uri_allow_transports : t -> ALLOW_TRANSPORT.t list -> unit
863 set the allowed transports in NBD URIs
865 Set which transports are allowed to appear in NBD URIs. The default is
867 to allow any transport.
868 The "mask" parameter may contain any of the following flags ORed
870 together:
871 "LIBNBD_ALLOW_TRANSPORT_TCP" "LIBNBD_ALLOW_TRANSPORT_UNIX"
873 "LIBNBD_ALLOW_TRANSPORT_VSOCK"
874 For convenience, the constant "LIBNBD_ALLOW_TRANSPORT_MASK" is avail‐
876 able to describe all transports recognized by this build of libnbd. A
877 future version of the library may add new flags.
878 val set_uri_allow_tls : t -> TLS.t -> unit
882 set the allowed TLS settings in NBD URIs
884 Set which TLS settings are allowed to appear in NBD URIs. The default
886 is to allow either non-TLS or TLS URIs.
887 The "tls" parameter can be:
889 "LIBNBD_TLS_DISABLE" TLS URIs are not permitted, ie. a URI such as
891 "nbds://..." will be rejected.
892 "LIBNBD_TLS_ALLOW" This is the default. TLS may be used or not, depend‐
894 ing on whether the URI uses "nbds" or "nbd".
895 "LIBNBD_TLS_REQUIRE" TLS URIs are required. All URIs must use "nbds".
897 val set_uri_allow_local_file : t -> bool -> unit
901 set the allowed transports in NBD URIs
903 Allow NBD URIs to reference local files. This is *disabled* by default.
905 Currently this setting only controls whether the "tls-psk-file" parame‐
907 ter in NBD URIs is allowed.
908 val connect_uri : t -> string -> unit
912 connect to NBD URI
914 Connect (synchronously) to an NBD server and export by specifying the
916 NBD URI. This call parses the URI and calls nbd_set_export_name(3) and
917 nbd_set_tls(3) and other calls as needed, followed by nbd_con‐
918 nect_tcp(3) or nbd_connect_unix(3). However, it is possible to override
919 the export name portion of a URI by using nbd_set_opt_mode(3) to enable
920 option mode, then using nbd_set_export_name(3) and nbd_opt_go(3) as
921 part of subsequent negotiation.
922 This call returns when the connection has been made.
924 Example URIs supported "nbd://example.com" Connect over TCP, unen‐
926 crypted, to "example.com" port 10809.
927 "nbds://example.com" Connect over TCP with TLS, to "example.com" port
929 10809. If the server does not support TLS then this will fail.
930 "nbd+unix:///foo?socket=/tmp/nbd.sock" Connect over the Unix domain
932 socket /tmp/nbd.sock to an NBD server running locally. The export name
933 is set to "foo" (note without any leading "/" character).
934 "nbd+vsock:///" In this scenario libnbd is running in a virtual
936 machine. Connect over "AF_VSOCK" to an NBD server running on the hyper‐
937 visor.
938 Supported URI formats The following schemes are supported in the cur‐
940 rent version of libnbd:
941 "nbd:" Connect over TCP without using TLS.
943 "nbds:" Connect over TCP. TLS is required and the connection will fail
945 if the server does not support TLS.
946 "nbd+unix:" "nbds+unix:" Connect over a Unix domain socket, without or
948 with TLS respectively. The "socket" parameter is required.
949 "nbd+vsock:" "nbds+vsock:" Connect over the "AF_VSOCK" transport, with‐
951 out or with TLS respectively.
952 The authority part of the URI (" username@ servername :port ") is
954 parsed depending on the transport. For TCP it specifies the server to
955 connect to and optional port number. For "+unix" it should not be
956 present. For "+vsock" the server name is the numeric CID (eg. 2 to con‐
957 nect to the host), and the optional port number may be present. If the
958 "username" is present it is used for TLS authentication.
959 For all transports, an export name may be present, parsed in accordance
961 with the NBD URI specification.
962 Finally the query part of the URI can contain:
964 socket=SOCKET Specifies the Unix domain socket to connect on. Must be
966 present for the "+unix" transport and must not be present for the other
967 transports.
968 tls-psk-file=PSKFILE Set the PSK file. See nbd_set_tls_psk_file(3).
970 Note this is not allowed by default - see next section.
971 Disable URI features For security reasons you might want to disable
973 certain URI features. Pre-filtering URIs is error-prone and should not
974 be attempted. Instead use the libnbd APIs below to control what can
975 appear in URIs. Note you must call these functions on the same handle
976 before calling nbd_connect_uri(3) or nbd_aio_connect_uri(3).
977 TCP, Unix domain socket or "AF_VSOCK" transports Default: all allowed
979 To select which transports are allowed call nbd_set_uri_allow_trans‐
981 ports(3).
982 TLS Default: both non-TLS and TLS connections allowed
984 To force TLS off or on in URIs call nbd_set_uri_allow_tls(3).
986 Connect to Unix domain socket in the local filesystem Default: allowed
988 To prevent this you must disable the "+unix" transport using
990 nbd_set_uri_allow_transports(3).
991 Read from local files Default: denied
993 To allow URIs to contain references to local files (eg. for parameters
995 like "tls-psk-file") call nbd_set_uri_allow_local_file(3).
996 Optional features This call will fail if libnbd was not compiled with
998 libxml2; you can test whether this is the case with nbd_sup‐
999 ports_uri(3).
1000 Support for URIs that require TLS will fail if libnbd was not compiled
1002 with gnutls; you can test whether this is the case with nbd_sup‐
1003 ports_tls(3).
1004 val connect_unix : t -> string -> unit
1008 connect to NBD server over a Unix domain socket
1010 Connect (synchronously) over the named Unix domain socket ("unix‐
1012 socket") to an NBD server running on the same machine. This call
1013 returns when the connection has been made.
1014 val connect_vsock : t -> int32 -> int32 -> unit
1018 connect to NBD server over AF_VSOCK protocol
1020 Connect (synchronously) over the "AF_VSOCK" protocol from a virtual
1022 machine to an NBD server, usually running on the host. The "cid" and
1023 "port" parameters specify the server address. Usually "cid" should be 2
1024 (to connect to the host), and "port" might be 10809 or another port
1025 number assigned to you by the host administrator. This call returns
1026 when the connection has been made.
1027 val connect_tcp : t -> string -> string -> unit
1031 connect to NBD server over a TCP port
1033 Connect (synchronously) to the NBD server listening on "hostname:port".
1035 The "port" may be a port name such as "nbd", or it may be a port number
1036 as a string such as "10809". This call returns when the connection has
1037 been made.
1038 val connect_socket : t -> Unix.file_descr -> unit
1042 connect directly to a connected socket
1044 Pass a connected socket "sock" through which libnbd will talk to the
1046 NBD server.
1047 The caller is responsible for creating and connecting this socket by
1049 some method, before passing it to libnbd.
1050 If this call returns without error then socket ownership is passed to
1052 libnbd. Libnbd will close the socket when the handle is closed. The
1053 caller must not use the socket in any way.
1054 val connect_command : t -> string list -> unit
1058 connect to NBD server command
1060 Run the command as a subprocess and connect to it over stdin/stdout.
1062 This is for use with NBD servers which can behave like inetd clients,
1063 such as "nbdkit --single".
1064 Subprocess Libnbd will fork the "argv" command and pass the NBD socket
1066 to it using file descriptors 0 and 1 (stdin/stdout):
1067 ┌─────────┬─────────┐ ┌────────────────┐ │ program │ libnbd │ │
1069 NBD server │ │ │ │ │ (argv) │ │ │
1070 socket ╍╍╍╍╍╍╍╍▶ stdin/stdout │ └─────────┴─────────┘
1071 └────────────────┘
1072 When the NBD handle is closed the server subprocess is killed.
1074 val connect_systemd_socket_activation : t -> string list -> unit
1078 connect using systemd socket activation
1080 Run the command as a subprocess and connect to it using systemd socket
1082 activation.
1083 This is especially useful for running qemu-nbd(1) as a subprocess of
1085 libnbd, for example to use it to open qcow2 files. To run nbdkit as a
1086 subprocess it is usually better to use nbd_connect_command(3).
1087 Socket activation Libnbd will fork the "argv" command and pass an NBD
1089 socket to it using special "LISTEN_*" environment variables (as defined
1090 by the systemd socket activation protocol).
1091 ┌─────────┬─────────┐ ┌───────────────┐ │ program │ libnbd │ │
1093 qemu-nbd or │ │ │ │ │ other server │ │ │
1094 socket ╍╍╍╍╍╍╍╍▶ │ └─────────┴─────────┘
1095 └───────────────┘
1096 When the NBD handle is closed the server subprocess is killed.
1098 val is_read_only : t -> bool
1102 is the NBD export read-only?
1104 Returns true if the NBD export is read-only; writes and write-like
1106 operations will fail.
1107 This call does not block, because it returns data that is saved in the
1109 handle from the NBD protocol handshake.
1110 val can_flush : t -> bool
1114 does the server support the flush command?
1116 Returns true if the server supports the flush command (see
1118 nbd_flush(3), nbd_aio_flush(3)). Returns false if the server does not.
1119 This call does not block, because it returns data that is saved in the
1121 handle from the NBD protocol handshake.
1122 val can_fua : t -> bool
1126 does the server support the FUA flag?
1128 Returns true if the server supports the FUA flag on certain commands
1130 (see nbd_pwrite(3)).
1131 This call does not block, because it returns data that is saved in the
1133 handle from the NBD protocol handshake.
1134 val is_rotational : t -> bool
1138 is the NBD disk rotational (like a disk)?
1140 Returns true if the disk exposed over NBD is rotational (like a tradi‐
1142 tional floppy or hard disk). Returns false if the disk has no penalty
1143 for random access (like an SSD or RAM disk).
1144 This call does not block, because it returns data that is saved in the
1146 handle from the NBD protocol handshake.
1147 val can_trim : t -> bool
1151 does the server support the trim command?
1153 Returns true if the server supports the trim command (see nbd_trim(3),
1155 nbd_aio_trim(3)). Returns false if the server does not.
1156 This call does not block, because it returns data that is saved in the
1158 handle from the NBD protocol handshake.
1159 val can_zero : t -> bool
1163 does the server support the zero command?
1165 Returns true if the server supports the zero command (see nbd_zero(3),
1167 nbd_aio_zero(3)). Returns false if the server does not.
1168 This call does not block, because it returns data that is saved in the
1170 handle from the NBD protocol handshake.
1171 val can_fast_zero : t -> bool
1175 does the server support the fast zero flag?
1177 Returns true if the server supports the use of the
1179 "LIBNBD_CMD_FLAG_FAST_ZERO" flag to the zero command (see nbd_zero(3),
1180 nbd_aio_zero(3)). Returns false if the server does not.
1181 This call does not block, because it returns data that is saved in the
1183 handle from the NBD protocol handshake.
1184 val can_df : t -> bool
1188 does the server support the don't fragment flag to pread?
1190 Returns true if the server supports structured reads with an ability to
1192 request a non-fragmented read (see nbd_pread_structured(3),
1193 nbd_aio_pread_structured(3)). Returns false if the server either lacks
1194 structured reads or if it does not support a non-fragmented read
1195 request.
1196 This call does not block, because it returns data that is saved in the
1198 handle from the NBD protocol handshake.
1199 val can_multi_conn : t -> bool
1203 does the server support multi-conn?
1205 Returns true if the server supports multi-conn. Returns false if the
1207 server does not.
1208 It is not safe to open multiple handles connecting to the same server
1210 if you will write to the server and the server does not advertise
1211 multi-conn support. The safe way to check for this is to open one con‐
1212 nection, check this flag is true, then open further connections as
1213 required.
1214 This call does not block, because it returns data that is saved in the
1216 handle from the NBD protocol handshake.
1217 val can_cache : t -> bool
1221 does the server support the cache command?
1223 Returns true if the server supports the cache command (see
1225 nbd_cache(3), nbd_aio_cache(3)). Returns false if the server does not.
1226 This call does not block, because it returns data that is saved in the
1228 handle from the NBD protocol handshake.
1229 val can_meta_context : t -> string -> bool
1233 does the server support a specific meta context?
1235 Returns true if the server supports the given meta context (see
1237 nbd_add_meta_context(3)). Returns false if the server does not.
1238 The single parameter is the name of the metadata context, for example
1240 "LIBNBD_CONTEXT_BASE_ALLOCATION". <libnbd.h> includes defined con‐
1241 stants for well-known namespace contexts beginning with "LIBNBD_CON‐
1242 TEXT_", but you are free to pass in other contexts.
1243 This call does not block, because it returns data that is saved in the
1245 handle from the NBD protocol handshake.
1246 val get_protocol : t -> string
1250 return the NBD protocol variant
1252 Return the NBD protocol variant in use on the connection. At the moment
1254 this returns one of the strings "oldstyle", "newstyle" or "new‐
1255 style-fixed". Other strings might be returned in the future. Most mod‐
1256 ern NBD servers use "newstyle-fixed".
1257 This call does not block, because it returns data that is saved in the
1259 handle from the NBD protocol handshake.
1260 val get_size : t -> int64
1264 return the export size
1266 Returns the size in bytes of the NBD export.
1268 This call does not block, because it returns data that is saved in the
1270 handle from the NBD protocol handshake.
1271 val get_block_size : t -> SIZE.t -> int64
1275 return a specific server block size constraint
1277 Returns a specific size constraint advertised by the server, if any. If
1279 the return is zero, the server did not advertise a constraint.
1280 "size_type" must be one of the following constraints:
1281 "LIBNBD_SIZE_MINIMUM" = 0 If non-zero, this will be a power of 2
1283 between 1 and 64k; any client request that is not aligned in length or
1284 offset to this size is likely to fail with "EINVAL". The image size
1285 will generally also be a multiple of this value (if not, the final few
1286 bytes are inaccessible while obeying alignment constraints). If zero,
1287 it is safest to assume a minimum block size of 512, although many
1288 servers support a minimum block size of 1. If the server provides a
1289 constraint, then libnbd defaults to honoring that constraint
1290 client-side unless "LIBNBD_STRICT_ALIGN" is cleared in
1291 nbd_set_strict_mode(3).
1292 "LIBNBD_SIZE_PREFERRED" = 1 If non-zero, this is a power of 2 repre‐
1294 senting the preferred size for efficient I/O. Smaller requests may
1295 incur overhead such as read-modify-write cycles that will not be
1296 present when using I/O that is a multiple of this value. This value may
1297 be larger than the size of the export. If zero, using 4k as a preferred
1298 block size tends to give decent performance.
1299 "LIBNBD_SIZE_MAXIMUM" = 2 If non-zero, this represents the maximum
1301 length that the server is willing to handle during nbd_pread(3) or
1302 nbd_pwrite(3). Other functions like nbd_zero(3) may still be able to
1303 use larger sizes. Note that this function returns what the server
1304 advertised, but libnbd itself imposes a maximum of 64M. If zero, some
1305 NBD servers will abruptly disconnect if a transaction involves more
1306 than 32M.
1307 Future NBD extensions may result in additional "size_type" values.
1309 This call does not block, because it returns data that is saved in the
1311 handle from the NBD protocol handshake.
1312 val pread : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 -> unit
1316 read from the NBD server
1318 Issue a read command to the NBD server for the range starting at "off‐
1320 set" and ending at "offset" + "count" - 1. NBD can only read all or
1321 nothing using this call. The call returns when the data has been read
1322 fully into "buf" or there is an error. See also nbd_pread_struc‐
1323 tured(3), if finer visibility is required into the server's replies, or
1324 if you want to use "LIBNBD_CMD_FLAG_DF".
1325 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
1327 tocol extensions).
1328 By default, libnbd will reject attempts to use this function with
1330 parameters that are likely to result in server failure, such as
1331 requesting an unknown command flag. The nbd_set_strict_mode(3) function
1332 can be used to alter which scenarios should await a server reply rather
1333 than failing fast.
1334 val pread_structured : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 ->
1338 (bytes -> int64 -> int -> int Stdlib.ref -> int) -> unit
1339 read from the NBD server
1341 Issue a read command to the NBD server for the range starting at "off‐
1343 set" and ending at "offset" + "count" - 1. The server's response may be
1344 subdivided into chunks which may arrive out of order before reassembly
1345 into the original buffer; the "chunk" callback is used for notification
1346 after each chunk arrives, and may perform additional sanity checking on
1347 the server's reply. The callback cannot call "nbd_*" APIs on the same
1348 handle since it holds the handle lock and will cause a deadlock. If the
1349 callback returns -1, and no earlier error has been detected, then the
1350 overall read command will fail with any non-zero value stored into the
1351 callback's "error" parameter (with a default of "EPROTO"); but any fur‐
1352 ther chunks will still invoke the callback.
1353 The "chunk" function is called once per chunk of data received, with
1355 the "user_data" passed to this function. The "subbuf" and "count"
1356 parameters represent the subset of the original buffer which has just
1357 been populated by results from the server (in C, "subbuf" always points
1358 within the original "buf"; but this guarantee may not extend to other
1359 language bindings). The "offset" parameter represents the absolute off‐
1360 set at which "subbuf" begins within the image (note that this is not
1361 the relative offset of "subbuf" within the original buffer "buf").
1362 Changes to "error" on output are ignored unless the callback fails. The
1363 input meaning of the "error" parameter is controlled by the "status"
1364 parameter, which is one of
1365 "LIBNBD_READ_DATA" = 1 "subbuf" was populated with "count" bytes of
1367 data. On input, "error" contains the errno value of any earlier
1368 detected error, or zero.
1369 "LIBNBD_READ_HOLE" = 2 "subbuf" represents a hole, and contains "count"
1371 NUL bytes. On input, "error" contains the errno value of any earlier
1372 detected error, or zero.
1373 "LIBNBD_READ_ERROR" = 3 "count" is 0, so "subbuf" is unusable. On
1375 input, "error" contains the errno value reported by the server as
1376 occurring while reading that "offset", regardless if any earlier error
1377 has been detected.
1378 Future NBD extensions may permit other values for "status", but those
1380 will not be returned to a client that has not opted in to requesting
1381 such extensions. If the server is non-compliant, it is possible for the
1382 "chunk" function to be called more times than you expect or with
1383 "count" 0 for "LIBNBD_READ_DATA" or "LIBNBD_READ_HOLE". It is also pos‐
1384 sible that the "chunk" function is not called at all (in particular,
1385 "LIBNBD_READ_ERROR" is used only when an error is associated with a
1386 particular offset, and not when the server reports a generic error),
1387 but you are guaranteed that the callback was called at least once if
1388 the overall read succeeds. Libnbd does not validate that the server
1389 obeyed the requirement that a read call must not have overlapping
1390 chunks and must not succeed without enough chunks to cover the entire
1391 request.
1392 The "flags" parameter may be 0 for no flags, or may contain
1394 "LIBNBD_CMD_FLAG_DF" meaning that the server should not reply with more
1395 than one fragment (if that is supported - some servers cannot do this,
1396 see nbd_can_df(3)). Libnbd does not validate that the server actually
1397 obeys the flag.
1398 By default, libnbd will reject attempts to use this function with
1400 parameters that are likely to result in server failure, such as
1401 requesting an unknown command flag. The nbd_set_strict_mode(3) function
1402 can be used to alter which scenarios should await a server reply rather
1403 than failing fast.
1404 val pwrite : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 -> unit
1408 write to the NBD server
1410 Issue a write command to the NBD server, writing the data in "buf" to
1412 the range starting at "offset" and ending at "offset" + "count" - 1.
1413 NBD can only write all or nothing using this call. The call returns
1414 when the command has been acknowledged by the server, or there is an
1415 error. Note this will generally return an error if nbd_is_read_only(3)
1416 is true.
1417 The "flags" parameter may be 0 for no flags, or may contain
1419 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
1420 the data has been committed to permanent storage (if that is supported
1421 - some servers cannot do this, see nbd_can_fua(3)).
1422 By default, libnbd will reject attempts to use this function with
1424 parameters that are likely to result in server failure, such as
1425 requesting an unknown command flag. The nbd_set_strict_mode(3) function
1426 can be used to alter which scenarios should await a server reply rather
1427 than failing fast.
1428 val shutdown : ?flags:SHUTDOWN.t list -> t -> unit
1432 disconnect from the NBD server
1434 Issue the disconnect command to the NBD server. This is a nice way to
1436 tell the server we are going away, but from the client's point of view
1437 has no advantage over abruptly closing the connection (see
1438 nbd_close(3)).
1439 This function works whether or not the handle is ready for transmission
1441 of commands. If more fine-grained control is needed, see nbd_aio_dis‐
1442 connect(3).
1443 The "flags" argument is a bitmask, including zero or more of the fol‐
1445 lowing shutdown flags:
1446 "LIBNBD_SHUTDOWN_ABANDON_PENDING" = 0x10000 If there are any pending
1448 requests which have not yet been sent to the server (see
1449 nbd_aio_in_flight(3)), abandon them without sending them to the server,
1450 rather than the usual practice of issuing those commands before inform‐
1451 ing the server of the intent to disconnect.
1452 For convenience, the constant "LIBNBD_SHUTDOWN_MASK" is available to
1454 describe all shutdown flags recognized by this build of libnbd. A
1455 future version of the library may add new flags.
1456 val flush : ?flags:CMD_FLAG.t list -> t -> unit
1460 send flush command to the NBD server
1462 Issue the flush command to the NBD server. The function should return
1464 when all write commands which have completed have been committed to
1465 permanent storage on the server. Note this will generally return an
1466 error if nbd_can_flush(3) is false.
1467 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
1469 tocol extensions).
1470 By default, libnbd will reject attempts to use this function with
1472 parameters that are likely to result in server failure, such as
1473 requesting an unknown command flag. The nbd_set_strict_mode(3) function
1474 can be used to alter which scenarios should await a server reply rather
1475 than failing fast.
1476 val trim : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
1480 send trim command to the NBD server
1482 Issue a trim command to the NBD server, which if supported by the
1484 server causes a hole to be punched in the backing store starting at
1485 "offset" and ending at "offset" + "count" - 1. The call returns when
1486 the command has been acknowledged by the server, or there is an error.
1487 Note this will generally return an error if nbd_can_trim(3) is false or
1488 nbd_is_read_only(3) is true.
1489 The "flags" parameter may be 0 for no flags, or may contain
1491 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
1492 the data has been committed to permanent storage (if that is supported
1493 - some servers cannot do this, see nbd_can_fua(3)).
1494 By default, libnbd will reject attempts to use this function with
1496 parameters that are likely to result in server failure, such as
1497 requesting an unknown command flag. The nbd_set_strict_mode(3) function
1498 can be used to alter which scenarios should await a server reply rather
1499 than failing fast.
1500 val cache : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
1504 send cache (prefetch) command to the NBD server
1506 Issue the cache (prefetch) command to the NBD server, which if sup‐
1508 ported by the server causes data to be prefetched into faster storage
1509 by the server, speeding up a subsequent nbd_pread(3) call. The server
1510 can also silently ignore this command. Note this will generally return
1511 an error if nbd_can_cache(3) is false.
1512 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
1514 tocol extensions).
1515 By default, libnbd will reject attempts to use this function with
1517 parameters that are likely to result in server failure, such as
1518 requesting an unknown command flag. The nbd_set_strict_mode(3) function
1519 can be used to alter which scenarios should await a server reply rather
1520 than failing fast.
1521 val zero : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
1525 send write zeroes command to the NBD server
1527 Issue a write zeroes command to the NBD server, which if supported by
1529 the server causes a zeroes to be written efficiently starting at "off‐
1530 set" and ending at "offset"
1531 -"count" - 1. The call returns when the command has been acknowledged
1533 by the server, or there is an error. Note this will generally return
1534 an error if nbd_can_zero(3) is false or nbd_is_read_only(3) is true.
1535 The "flags" parameter may be 0 for no flags, or may contain
1537 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
1538 the data has been committed to permanent storage (if that is supported
1539 - some servers cannot do this, see nbd_can_fua(3)),
1540 "LIBNBD_CMD_FLAG_NO_HOLE" meaning that the server should favor writing
1541 actual allocated zeroes over punching a hole, and/or
1542 "LIBNBD_CMD_FLAG_FAST_ZERO" meaning that the server must fail quickly
1543 if writing zeroes is no faster than a normal write (if that is sup‐
1544 ported - some servers cannot do this, see nbd_can_fast_zero(3)).
1545 By default, libnbd will reject attempts to use this function with
1547 parameters that are likely to result in server failure, such as
1548 requesting an unknown command flag. The nbd_set_strict_mode(3) function
1549 can be used to alter which scenarios should await a server reply rather
1550 than failing fast.
1551 val block_status : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 ->
1555 (string -> int64 -> int32 array -> int Stdlib.ref -> int) -> unit
1556 send block status command to the NBD server
1558 Issue the block status command to the NBD server. If supported by the
1560 server, this causes metadata context information about blocks beginning
1561 from the specified offset to be returned. The "count" parameter is a
1562 hint: the server may choose to return less status, or the final block
1563 may extend beyond the requested range. If multiple contexts are sup‐
1564 ported, the number of blocks and cumulative length of those blocks need
1565 not be identical between contexts.
1566 Depending on which metadata contexts were enabled before connecting
1568 (see nbd_add_meta_context(3)) and which are supported by the server
1569 (see nbd_can_meta_context(3)) this call returns information about
1570 extents by calling back to the "extent" function. The callback cannot
1571 call "nbd_*" APIs on the same handle since it holds the handle lock and
1572 will cause a deadlock. If the callback returns -1, and no earlier error
1573 has been detected, then the overall block status command will fail with
1574 any non-zero value stored into the callback's "error" parameter (with a
1575 default of "EPROTO"); but any further contexts will still invoke the
1576 callback.
1577 The "extent" function is called once per type of metadata available,
1579 with the "user_data" passed to this function. The "metacontext" parame‐
1580 ter is a string such as "base:allocation". The "entries" array is an
1581 array of pairs of integers with the first entry in each pair being the
1582 length (in bytes) of the block and the second entry being a sta‐
1583 tus/flags field which is specific to the metadata context. (The number
1584 of pairs passed to the function is "nr_entries/2".) The NBD protocol
1585 document in the section about "NBD_REPLY_TYPE_BLOCK_STATUS" describes
1586 the meaning of this array; for contexts known to libnbd, <libnbd.h>
1587 contains constants beginning with "LIBNBD_STATE_" that may help deci‐
1588 pher the values. On entry to the callback, the "error" parameter con‐
1589 tains the errno value of any previously detected error.
1590 It is possible for the extent function to be called more times than you
1592 expect (if the server is buggy), so always check the "metacontext"
1593 field to ensure you are receiving the data you expect. It is also pos‐
1594 sible that the extent function is not called at all, even for metadata
1595 contexts that you requested. This indicates either that the server
1596 doesn't support the context or for some other reason cannot return the
1597 data.
1598 The "flags" parameter may be 0 for no flags, or may contain
1600 "LIBNBD_CMD_FLAG_REQ_ONE" meaning that the server should return only
1601 one extent per metadata context where that extent does not exceed
1602 "count" bytes; however, libnbd does not validate that the server obeyed
1603 the flag.
1604 By default, libnbd will reject attempts to use this function with
1606 parameters that are likely to result in server failure, such as
1607 requesting an unknown command flag. The nbd_set_strict_mode(3) function
1608 can be used to alter which scenarios should await a server reply rather
1609 than failing fast.
1610 val poll : t -> int -> int
1614 poll the handle once
1616 This is a simple implementation of poll(2) which is used internally by
1618 synchronous API calls. On success, it returns 0 if the "timeout" (in
1619 milliseconds) occurs, or 1 if the poll completed and the state machine
1620 progressed. Set "timeout" to -1 to block indefinitely (but be careful
1621 that eventual action is actually expected - for example, if the connec‐
1622 tion is established but there are no commands in flight, using an infi‐
1623 nite timeout will permanently block).
1624 This function is mainly useful as an example of how you might integrate
1626 libnbd with your own main loop, rather than being intended as something
1627 you would use.
1628 val aio_connect : t -> string -> unit
1632 connect to the NBD server
1634 Begin connecting to the NBD server. The "addr" and "addrlen" parameters
1636 specify the address of the socket to connect to.
1637 You can check if the connection is still connecting by calling
1639 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1640 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1641 tion.
1642 val aio_connect_uri : t -> string -> unit
1646 connect to an NBD URI
1648 Begin connecting to the NBD URI "uri". Parameters behave as documented
1650 in nbd_connect_uri(3).
1651 You can check if the connection is still connecting by calling
1653 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1654 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1655 tion.
1656 val aio_connect_unix : t -> string -> unit
1660 connect to the NBD server over a Unix domain socket
1662 Begin connecting to the NBD server over Unix domain socket ("unix‐
1664 socket"). Parameters behave as documented in nbd_connect_unix(3).
1665 You can check if the connection is still connecting by calling
1667 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1668 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1669 tion.
1670 val aio_connect_vsock : t -> int32 -> int32 -> unit
1674 connect to the NBD server over AF_VSOCK socket
1676 Begin connecting to the NBD server over the "AF_VSOCK" protocol to the
1678 server "cid:port". Parameters behave as documented in nbd_con‐
1679 nect_vsock(3).
1680 You can check if the connection is still connecting by calling
1682 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1683 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1684 tion.
1685 val aio_connect_tcp : t -> string -> string -> unit
1689 connect to the NBD server over a TCP port
1691 Begin connecting to the NBD server listening on "hostname:port". Param‐
1693 eters behave as documented in nbd_connect_tcp(3).
1694 You can check if the connection is still connecting by calling
1696 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1697 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1698 tion.
1699 val aio_connect_socket : t -> Unix.file_descr -> unit
1703 connect directly to a connected socket
1705 Begin connecting to the connected socket "fd". Parameters behave as
1707 documented in nbd_connect_socket(3).
1708 You can check if the connection is still connecting by calling
1710 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1711 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1712 tion.
1713 val aio_connect_command : t -> string list -> unit
1717 connect to the NBD server
1719 Run the command as a subprocess and begin connecting to it over
1721 stdin/stdout. Parameters behave as documented in nbd_connect_com‐
1722 mand(3).
1723 You can check if the connection is still connecting by calling
1725 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1726 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1727 tion.
1728 val aio_connect_systemd_socket_activation : t -> string list -> unit
1732 connect using systemd socket activation
1734 Run the command as a subprocess and begin connecting to it using sys‐
1736 temd socket activation. Parameters behave as documented in nbd_con‐
1737 nect_systemd_socket_activation(3).
1738 You can check if the connection is still connecting by calling
1740 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1741 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1742 tion.
1743 val aio_opt_go : ?completion:(int Stdlib.ref -> int) -> t -> unit
1747 end negotiation and move on to using an export
1749 Request that the server finish negotiation and move on to serving the
1751 export previously specified by the most recent nbd_set_export_name(3)
1752 or nbd_connect_uri(3). This can only be used if nbd_set_opt_mode(3)
1753 enabled option mode.
1754 To determine when the request completes, wait for nbd_aio_is_connect‐
1756 ing(3) to return false. Or supply the optional "completion_callback"
1757 which will be invoked as described in "Completion callbacks" in
1758 libnbd(3), except that it is automatically retired regardless of return
1759 value. Note that directly detecting whether the server returns an error
1760 (as is done by the return value of the synchronous counterpart) is only
1761 possible with a completion callback; however it is also possible to
1762 indirectly detect an error when nbd_aio_is_negotiating(3) returns true.
1763 val aio_opt_abort : t -> unit
1767 end negotiation and close the connection
1769 Request that the server finish negotiation, gracefully if possible,
1771 then close the connection. This can only be used if nbd_set_opt_mode(3)
1772 enabled option mode.
1773 To determine when the request completes, wait for nbd_aio_is_connect‐
1775 ing(3) to return false.
1776 val aio_opt_list : ?completion:(int Stdlib.ref -> int) -> t -> (string
1780 -> string -> int) -> unit
1781 request the server to list all exports during negotiation
1783 Request that the server list all exports that it supports. This can
1785 only be used if nbd_set_opt_mode(3) enabled option mode.
1786 To determine when the request completes, wait for nbd_aio_is_connect‐
1788 ing(3) to return false. Or supply the optional "completion_callback"
1789 which will be invoked as described in "Completion callbacks" in
1790 libnbd(3), except that it is automatically retired regardless of return
1791 value. Note that detecting whether the server returns an error (as is
1792 done by the return value of the synchronous counterpart) is only possi‐
1793 ble with a completion callback.
1794 val aio_opt_info : ?completion:(int Stdlib.ref -> int) -> t -> unit
1798 request the server for information about an export
1800 Request that the server supply information about the export name previ‐
1802 ously specified by the most recent nbd_set_export_name(3) or nbd_con‐
1803 nect_uri(3). This can only be used if nbd_set_opt_mode(3) enabled
1804 option mode.
1805 To determine when the request completes, wait for nbd_aio_is_connect‐
1807 ing(3) to return false. Or supply the optional "completion_callback"
1808 which will be invoked as described in "Completion callbacks" in
1809 libnbd(3), except that it is automatically retired regardless of return
1810 value. Note that detecting whether the server returns an error (as is
1811 done by the return value of the synchronous counterpart) is only possi‐
1812 ble with a completion callback.
1813 val aio_opt_list_meta_context : ?completion:(int Stdlib.ref -> int) ->
1817 t -> (string -> int) -> int
1818 request the server to list available meta contexts
1820 Request that the server list available meta contexts associated with
1822 the export previously specified by the most recent
1823 nbd_set_export_name(3) or nbd_connect_uri(3). This can only be used if
1824 nbd_set_opt_mode(3) enabled option mode.
1825 To determine when the request completes, wait for nbd_aio_is_connect‐
1827 ing(3) to return false. Or supply the optional "completion_callback"
1828 which will be invoked as described in "Completion callbacks" in
1829 libnbd(3), except that it is automatically retired regardless of return
1830 value. Note that detecting whether the server returns an error (as is
1831 done by the return value of the synchronous counterpart) is only possi‐
1832 ble with a completion callback.
1833 val aio_pread : ?completion:(int Stdlib.ref -> int) ->
1837 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> cookie
1838 read from the NBD server
1840 Issue a read command to the NBD server.
1842 To check if the command completed, call nbd_aio_command_completed(3).
1844 Or supply the optional "completion_callback" which will be invoked as
1845 described in "Completion callbacks" in libnbd(3).
1846 Note that you must ensure "buf" is valid until the command has com‐
1848 pleted. Other parameters behave as documented in nbd_pread(3).
1849 By default, libnbd will reject attempts to use this function with
1851 parameters that are likely to result in server failure, such as
1852 requesting an unknown command flag. The nbd_set_strict_mode(3) function
1853 can be used to alter which scenarios should await a server reply rather
1854 than failing fast.
1855 val aio_pread_structured : ?completion:(int Stdlib.ref -> int) ->
1859 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> (bytes -> int64 ->
1860 int -> int Stdlib.ref -> int) -> cookie
1861 read from the NBD server
1863 Issue a read command to the NBD server.
1865 To check if the command completed, call nbd_aio_command_completed(3).
1867 Or supply the optional "completion_callback" which will be invoked as
1868 described in "Completion callbacks" in libnbd(3).
1869 Other parameters behave as documented in nbd_pread_structured(3).
1871 By default, libnbd will reject attempts to use this function with
1873 parameters that are likely to result in server failure, such as
1874 requesting an unknown command flag. The nbd_set_strict_mode(3) function
1875 can be used to alter which scenarios should await a server reply rather
1876 than failing fast.
1877 val aio_pwrite : ?completion:(int Stdlib.ref -> int) ->
1881 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> cookie
1882 write to the NBD server
1884 Issue a write command to the NBD server.
1886 To check if the command completed, call nbd_aio_command_completed(3).
1888 Or supply the optional "completion_callback" which will be invoked as
1889 described in "Completion callbacks" in libnbd(3).
1890 Note that you must ensure "buf" is valid until the command has com‐
1892 pleted. Other parameters behave as documented in nbd_pwrite(3).
1893 By default, libnbd will reject attempts to use this function with
1895 parameters that are likely to result in server failure, such as
1896 requesting an unknown command flag. The nbd_set_strict_mode(3) function
1897 can be used to alter which scenarios should await a server reply rather
1898 than failing fast.
1899 val aio_disconnect : ?flags:CMD_FLAG.t list -> t -> unit
1903 disconnect from the NBD server
1905 Issue the disconnect command to the NBD server. This is not a normal
1907 command because NBD servers are not obliged to send a reply. Instead
1908 you should wait for nbd_aio_is_closed(3) to become true on the connec‐
1909 tion. Once this command is issued, you cannot issue any further com‐
1910 mands.
1911 Although libnbd does not prevent you from issuing this command while
1913 still waiting on the replies to previous commands, the NBD protocol
1914 recommends that you wait until there are no other commands in flight
1915 (see nbd_aio_in_flight(3)), to give the server a better chance at a
1916 clean shutdown.
1917 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
1919 tocol extensions). There is no direct synchronous counterpart; however,
1920 nbd_shutdown(3) will call this function if appropriate.
1921 val aio_flush : ?completion:(int Stdlib.ref -> int) ->
1925 ?flags:CMD_FLAG.t list -> t -> cookie
1926 send flush command to the NBD server
1928 Issue the flush command to the NBD server.
1930 To check if the command completed, call nbd_aio_command_completed(3).
1932 Or supply the optional "completion_callback" which will be invoked as
1933 described in "Completion callbacks" in libnbd(3).
1934 Other parameters behave as documented in nbd_flush(3).
1936 By default, libnbd will reject attempts to use this function with
1938 parameters that are likely to result in server failure, such as
1939 requesting an unknown command flag. The nbd_set_strict_mode(3) function
1940 can be used to alter which scenarios should await a server reply rather
1941 than failing fast.
1942 val aio_trim : ?completion:(int Stdlib.ref -> int) -> ?flags:CMD_FLAG.t
1946 list -> t -> int64 -> int64 -> cookie
1947 send trim command to the NBD server
1949 Issue a trim command to the NBD server.
1951 To check if the command completed, call nbd_aio_command_completed(3).
1953 Or supply the optional "completion_callback" which will be invoked as
1954 described in "Completion callbacks" in libnbd(3).
1955 Other parameters behave as documented in nbd_trim(3).
1957 By default, libnbd will reject attempts to use this function with
1959 parameters that are likely to result in server failure, such as
1960 requesting an unknown command flag. The nbd_set_strict_mode(3) function
1961 can be used to alter which scenarios should await a server reply rather
1962 than failing fast.
1963 val aio_cache : ?completion:(int Stdlib.ref -> int) ->
1967 ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> cookie
1968 send cache (prefetch) command to the NBD server
1970 Issue the cache (prefetch) command to the NBD server.
1972 To check if the command completed, call nbd_aio_command_completed(3).
1974 Or supply the optional "completion_callback" which will be invoked as
1975 described in "Completion callbacks" in libnbd(3).
1976 Other parameters behave as documented in nbd_cache(3).
1978 By default, libnbd will reject attempts to use this function with
1980 parameters that are likely to result in server failure, such as
1981 requesting an unknown command flag. The nbd_set_strict_mode(3) function
1982 can be used to alter which scenarios should await a server reply rather
1983 than failing fast.
1984 val aio_zero : ?completion:(int Stdlib.ref -> int) -> ?flags:CMD_FLAG.t
1988 list -> t -> int64 -> int64 -> cookie
1989 send write zeroes command to the NBD server
1991 Issue a write zeroes command to the NBD server.
1993 To check if the command completed, call nbd_aio_command_completed(3).
1995 Or supply the optional "completion_callback" which will be invoked as
1996 described in "Completion callbacks" in libnbd(3).
1997 Other parameters behave as documented in nbd_zero(3).
1999 By default, libnbd will reject attempts to use this function with
2001 parameters that are likely to result in server failure, such as
2002 requesting an unknown command flag. The nbd_set_strict_mode(3) function
2003 can be used to alter which scenarios should await a server reply rather
2004 than failing fast.
2005 val aio_block_status : ?completion:(int Stdlib.ref -> int) ->
2009 ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> (string -> int64 ->
2010 int32 array -> int Stdlib.ref -> int) -> cookie
2011 send block status command to the NBD server
2013 Send the block status command to the NBD server.
2015 To check if the command completed, call nbd_aio_command_completed(3).
2017 Or supply the optional "completion_callback" which will be invoked as
2018 described in "Completion callbacks" in libnbd(3).
2019 Other parameters behave as documented in nbd_block_status(3).
2021 By default, libnbd will reject attempts to use this function with
2023 parameters that are likely to result in server failure, such as
2024 requesting an unknown command flag. The nbd_set_strict_mode(3) function
2025 can be used to alter which scenarios should await a server reply rather
2026 than failing fast.
2027 val aio_get_fd : t -> Unix.file_descr
2031 return file descriptor associated with this connection
2033 Return the underlying file descriptor associated with this connection.
2035 You can use this to check if the file descriptor is ready for reading
2036 or writing and call nbd_aio_notify_read(3) or nbd_aio_notify_write(3).
2037 See also nbd_aio_get_direction(3). Do not do anything else with the
2038 file descriptor.
2039 val aio_get_direction : t -> int
2043 return the read or write direction
2045 Return the current direction of this connection, which means whether we
2047 are next expecting to read data from the server, write data to the
2048 server, or both. It returns
2049 0 We are not expected to interact with the server file descriptor
2051 from the current state. It is not worth attempting to use poll(2); if
2052 the connection is not dead, then state machine progress must instead
2053 come from some other means such as nbd_aio_connect(3).
2054 "LIBNBD_AIO_DIRECTION_READ" = 1 We are expected next to read from the
2056 server. If using poll(2) you would set "events = POLLIN". If "revents"
2057 returns "POLLIN" or "POLLHUP" you would then call
2058 nbd_aio_notify_read(3).
2059 Note that once libnbd reaches nbd_aio_is_ready(3), this direction is
2061 returned even when there are no commands in flight (see
2062 nbd_aio_in_flight(3)). In a single-threaded use of libnbd, it is not
2063 worth polling until after issuing a command, as otherwise the server
2064 will never wake up the poll. In a multi-threaded scenario, you can have
2065 one thread begin a polling loop prior to any commands, but any other
2066 thread that issues a command will need a way to kick the polling thread
2067 out of poll in case issuing the command changes the needed polling
2068 direction. Possible ways to do this include polling for activity on a
2069 pipe-to-self, or using pthread_kill(3) to send a signal that is masked
2070 except during ppoll(2).
2071 "LIBNBD_AIO_DIRECTION_WRITE" = 2 We are expected next to write to the
2073 server. If using poll(2) you would set "events = POLLOUT". If "revents"
2074 returns "POLLOUT" you would then call nbd_aio_notify_write(3).
2075 "LIBNBD_AIO_DIRECTION_BOTH" = 3 We are expected next to either read or
2077 write to the server. If using poll(2) you would set "events =
2078 POLLIN|POLLOUT". If only one of "POLLIN" or "POLLOUT" is returned, then
2079 see above. However, if both are returned, it is better to call only
2080 nbd_aio_notify_read(3), as processing the server's reply may change the
2081 state of the connection and invalidate the need to write more commands.
2082 val aio_notify_read : t -> unit
2086 notify that the connection is readable
2088 Send notification to the state machine that the connection is readable.
2090 Typically this is called after your main loop has detected that the
2091 file descriptor associated with this connection is readable.
2092 val aio_notify_write : t -> unit
2096 notify that the connection is writable
2098 Send notification to the state machine that the connection is writable.
2100 Typically this is called after your main loop has detected that the
2101 file descriptor associated with this connection is writable.
2102 val aio_is_created : t -> bool
2106 check if the connection has just been created
2108 Return true if this connection has just been created. This is the
2110 state before the handle has started connecting to a server. In this
2111 state the handle can start to be connected by calling functions such as
2112 nbd_aio_connect(3).
2113 val aio_is_connecting : t -> bool
2117 check if the connection is connecting or handshaking
2119 Return true if this connection is connecting to the server or in the
2121 process of handshaking and negotiating options which happens before the
2122 handle becomes ready to issue commands (see nbd_aio_is_ready(3)).
2123 val aio_is_negotiating : t -> bool
2127 check if connection is ready to send handshake option
2129 Return true if this connection is ready to start another option negoti‐
2131 ation command while handshaking with the server. An option command will
2132 move back to the connecting state (see nbd_aio_is_connecting(3)). Note
2133 that this state cannot be reached unless requested by
2134 nbd_set_opt_mode(3), and even then it only works with newstyle servers;
2135 an oldstyle server will skip straight to nbd_aio_is_ready(3).
2136 val aio_is_ready : t -> bool
2140 check if the connection is in the ready state
2142 Return true if this connection is connected to the NBD server, the
2144 handshake has completed, and the connection is idle or waiting for a
2145 reply. In this state the handle is ready to issue commands.
2146 val aio_is_processing : t -> bool
2150 check if the connection is processing a command
2152 Return true if this connection is connected to the NBD server, the
2154 handshake has completed, and the connection is processing commands
2155 (either writing out a request or reading a reply).
2156 Note the ready state (nbd_aio_is_ready(3)) is not included. In the
2158 ready state commands may be *in flight* (the *server* is processing
2159 them), but libnbd is not processing them.
2160 val aio_is_dead : t -> bool
2164 check if the connection is dead
2166 Return true if the connection has encountered a fatal error and is
2168 dead. In this state the handle may only be closed. There is no way to
2169 recover a handle from the dead state.
2170 val aio_is_closed : t -> bool
2174 check if the connection is closed
2176 Return true if the connection has closed. There is no way to reconnect
2178 a closed connection. Instead you must close the whole handle.
2179 val aio_command_completed : t -> int64 -> bool
2183 check if the command completed
2185 Return true if the command completed. If this function returns true
2187 then the command was successful and it has been retired. Return false
2188 if the command is still in flight. This can also fail with an error in
2189 case the command failed (in this case the command is also retired). A
2190 command is retired either via this command, or by using a completion
2191 callback which returns 1.
2192 The "cookie" parameter is the positive unique 64 bit cookie for the
2194 command, as returned by a call such as nbd_aio_pread(3).
2195 val aio_peek_command_completed : t -> int64
2199 check if any command has completed
2201 Return the unique positive 64 bit cookie of the first non-retired but
2203 completed command, 0 if there are in-flight commands but none of them
2204 are awaiting retirement, or -1 on error including when there are no
2205 in-flight commands. Any cookie returned by this function must still be
2206 passed to nbd_aio_command_completed(3) to actually retire the command
2207 and learn whether the command was successful.
2208 val aio_in_flight : t -> int
2212 check how many aio commands are still in flight
2214 Return the number of in-flight aio commands that are still awaiting a
2216 response from the server before they can be retired. If this returns a
2217 non-zero value when requesting a disconnect from the server (see
2218 nbd_aio_disconnect(3) and nbd_shutdown(3)), libnbd does not try to wait
2219 for those commands to complete gracefully; if the server strands com‐
2220 mands while shutting down, nbd_aio_command_completed(3) will report
2221 those commands as failed with a status of "ENOTCONN".
2222 val connection_state : t -> string
2226 return string describing the state of the connection
2228 Returns a descriptive string for the state of the connection. This can
2230 be used for debugging or troubleshooting, but you should not rely on
2231 the state of connections since it may change in future versions.
2232 val get_package_name : t -> string
2236 return the name of the library
2238 Returns the name of the library, always "libnbd" unless the library was
2240 modified with another name at compile time.
2241 val get_version : t -> string
2245 return the version of the library
2247 Return the version of libnbd. This is returned as a string in the form
2249 "major.minor.release" where each of major, minor and release is a small
2250 positive integer. For example:
2251 minor ↓ "1.0.3" ↑ ↑ major release
2253 major = 0 The major number was 0 for the early experimental versions of
2255 libnbd where we still had an unstable API.
2256 major = 1 The major number is 1 for the versions of libnbd with a
2258 long-term stable API and ABI. It is not anticipated that major will be
2259 any number other than 1.
2260 minor = 0, 2, ... (even) The minor number is even for stable releases.
2262 minor = 1, 3, ... (odd) The minor number is odd for development ver‐
2264 sions. Note that new APIs added in a development version remain exper‐
2265 imental and subject to change in that branch until they appear in a
2266 stable release.
2267 release The release number is incremented for each release along a par‐
2269 ticular branch.
2270 val kill_subprocess : t -> int -> unit
2274 kill server running as a subprocess
2276 This call may be used to kill the server running as a subprocess that
2278 was previously created using nbd_connect_command(3). You do not need to
2279 use this call. It is only needed if the server does not exit when the
2280 socket is closed.
2281 The "signum" parameter is the optional signal number to send (see sig‐
2283 nal(7)). If "signum" is 0 then "SIGTERM" is sent.
2284 val supports_tls : t -> bool
2288 true if libnbd was compiled with support for TLS
2290 Returns true if libnbd was compiled with gnutls which is required to
2292 support TLS encryption, or false if not.
2293 val supports_uri : t -> bool
2297 true if libnbd was compiled with support for NBD URIs
2299 Returns true if libnbd was compiled with libxml2 which is required to
2301 support NBD URIs, or false if not.
2302OCamldoc 2021-03-02 NBD(3)