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 pa‐
190 rameters 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_private_data : t -> int -> int
235 set the per-handle private data
237 Handles contain a private data field for applications to use for any
239 purpose.
240 When calling libnbd from C, the type of this field is "uintptr_t" so it
242 can be used to store an unsigned integer or a pointer.
243 In non-C bindings it can be used to store an unsigned integer.
245 This function sets the value of this field and returns the old value
247 (or 0 if it was not previously set).
248 val get_private_data : t -> int
252 get the per-handle private data
254 Return the value of the private data field set previously by a call to
256 nbd_set_private_data(3) (or 0 if it was not previously set).
257 val set_export_name : t -> string -> unit
261 set the export name
263 For servers which require an export name or can serve different content
265 on different exports, set the "export_name" to connect to. The default
266 is the empty string "".
267 This is only relevant when connecting to servers using the newstyle
269 protocol as the oldstyle protocol did not support export names. The NBD
270 protocol limits export names to 4096 bytes, but servers may not support
271 the full length. The encoding of export names is always UTF-8.
272 When option mode is not in use, the export name must be set before be‐
274 ginning a connection. However, when nbd_set_opt_mode(3) has enabled op‐
275 tion mode, it is possible to change the export name prior to
276 nbd_opt_go(3). In particular, the use of nbd_opt_list(3) during negoti‐
277 ation can be used to determine a name the server is likely to accept,
278 and nbd_opt_info(3) can be used to learn details about an export before
279 connecting.
280 This call may be skipped if using nbd_connect_uri(3) to connect to a
282 URI that includes an export name.
283 val get_export_name : t -> string
287 get the export name
289 Get the export name associated with the handle. This is the name that
291 libnbd requests; see nbd_get_canonical_export_name(3) for determining
292 if the server has a different canonical name for the given export (most
293 common when requesting the default export name of an empty string "")
294 val set_full_info : t -> bool -> unit
298 control whether NBD_OPT_GO requests extra details
300 By default, when connecting to an export, libnbd only requests the de‐
302 tails it needs to service data operations. The NBD protocol says that a
303 server can supply optional information, such as a canonical name of the
304 export (see nbd_get_canonical_export_name(3)) or a description of the
305 export (see nbd_get_export_description(3)), but that a hint from the
306 client makes it more likely for this extra information to be provided.
307 This function controls whether libnbd will provide that hint.
308 Note that even when full info is requested, the server is not obligated
310 to reply with all information that libnbd requested. Similarly, libnbd
311 will ignore any optional server information that libnbd has not yet
312 been taught to recognize.
313 val get_full_info : t -> bool
317 see if NBD_OPT_GO requests extra details
319 Return the state of the full info request flag on this handle.
321 val get_canonical_export_name : t -> string
325 return the canonical export name, if the server has one
327 The NBD protocol permits a server to report an optional canonical ex‐
329 port name, which may differ from the client's request (as set by
330 nbd_set_export_name(3) or nbd_connect_uri(3)). This function accesses
331 any name returned by the server; it may be the same as the client re‐
332 quest, but is more likely to differ when the client requested a connec‐
333 tion to the default export name (an empty string "").
334 Some servers are unlikely to report a canonical name unless the client
336 specifically hinted about wanting it, via nbd_set_full_info(3).
337 val get_export_description : t -> string
341 return the export description, if the server has one
343 The NBD protocol permits a server to report an optional export descrip‐
345 tion. This function reports any description returned by the server.
346 Some servers are unlikely to report a description unless the client
348 specifically hinted about wanting it, via nbd_set_full_info(3). For
349 qemu-nbd(8), a description is set with *-D*.
350 val set_tls : t -> TLS.t -> unit
354 enable or require TLS (authentication and encryption)
356 Enable or require TLS (authenticated and encrypted connections) to the
358 NBD server. The possible settings are:
359 "LIBNBD_TLS_DISABLE" Disable TLS. (The default setting, unless using
361 nbd_connect_uri(3) with a URI that requires TLS)
362 "LIBNBD_TLS_ALLOW" Enable TLS if possible.
364 This option is insecure (or best effort) in that in some cases it will
366 fall back to an unencrypted and/or unauthenticated connection if TLS
367 could not be established. Use "LIBNBD_TLS_REQUIRE" below if the connec‐
368 tion must be encrypted.
369 Some servers will drop the connection if TLS fails so fallback may not
371 be possible.
372 "LIBNBD_TLS_REQUIRE" Require an encrypted and authenticated TLS connec‐
374 tion. Always fail to connect if the connection is not encrypted and au‐
375 thenticated.
376 As well as calling this you may also need to supply the path to the
378 certificates directory (nbd_set_tls_certificates(3)), the username
379 (nbd_set_tls_username(3)) and/or the Pre-Shared Keys (PSK) file
380 (nbd_set_tls_psk_file(3)). For now, when using nbd_connect_uri(3), any
381 URI query parameters related to TLS are not handled automatically. Set‐
382 ting the level higher than zero will fail if libnbd was not compiled
383 against gnutls; you can test whether this is the case with nbd_sup‐
384 ports_tls(3).
385 val get_tls : t -> TLS.t
389 get the TLS request setting
391 Get the TLS request setting.
393 Note: If you want to find out if TLS was actually negotiated on a par‐
395 ticular connection use nbd_get_tls_negotiated(3) instead.
396 val get_tls_negotiated : t -> bool
400 find out if TLS was negotiated on a connection
402 After connecting you may call this to find out if the connection is us‐
404 ing TLS.
405 This is only really useful if you set the TLS request mode to
407 "LIBNBD_TLS_ALLOW" (see nbd_set_tls(3)), because in this mode we try to
408 use TLS but fall back to unencrypted if it was not available. This
409 function will tell you if TLS was negotiated or not.
410 In "LIBNBD_TLS_REQUIRE" mode (the most secure) the connection would
412 have failed if TLS could not be negotiated, and in "LIBNBD_TLS_DISABLE"
413 mode TLS is not tried.
414 val set_tls_certificates : t -> string -> unit
418 set the path to the TLS certificates directory
420 Set the path to the TLS certificates directory. If not set and TLS is
422 used then a compiled in default is used. For root this is
423 "/etc/pki/libnbd/". For non-root this is "$HOME/.pki/libnbd" and
424 "$HOME/.config/pki/libnbd". If none of these directories can be found
425 then the system trusted CAs are used.
426 This function may be called regardless of whether TLS is supported, but
428 will have no effect unless nbd_set_tls(3) is also used to request or
429 require TLS.
430 val set_tls_verify_peer : t -> bool -> unit
434 set whether we verify the identity of the server
436 Set this flag to control whether libnbd will verify the identity of the
438 server from the server's certificate and the certificate authority.
439 This defaults to true when connecting to TCP servers using TLS certifi‐
440 cate authentication, and false otherwise.
441 This function may be called regardless of whether TLS is supported, but
443 will have no effect unless nbd_set_tls(3) is also used to request or
444 require TLS.
445 val get_tls_verify_peer : t -> bool
449 get whether we verify the identity of the server
451 Get the verify peer flag.
453 val set_tls_username : t -> string -> unit
457 set the TLS username
459 Set the TLS client username. This is used if authenticating with PSK
461 over TLS is enabled. If not set then the local username is used.
462 This function may be called regardless of whether TLS is supported, but
464 will have no effect unless nbd_set_tls(3) is also used to request or
465 require TLS.
466 val get_tls_username : t -> string
470 get the current TLS username
472 Get the current TLS username.
474 val set_tls_psk_file : t -> string -> unit
478 set the TLS Pre-Shared Keys (PSK) filename
480 Set the TLS Pre-Shared Keys (PSK) filename. This is used if trying to
482 authenticate to the server using with a pre-shared key. There is no de‐
483 fault so if this is not set then PSK authentication cannot be used to
484 connect to the server.
485 This function may be called regardless of whether TLS is supported, but
487 will have no effect unless nbd_set_tls(3) is also used to request or
488 require TLS.
489 val set_request_structured_replies : t -> bool -> unit
493 control use of structured replies
495 By default, libnbd tries to negotiate structured replies with the
497 server, as this protocol extension must be in use before
498 nbd_can_meta_context(3) or nbd_can_df(3) can return true. However, for
499 integration testing, it can be useful to clear this flag rather than
500 find a way to alter the server to fail the negotiation request.
501 val get_request_structured_replies : t -> bool
505 see if structured replies are attempted
507 Return the state of the request structured replies flag on this handle.
509 Note: If you want to find out if structured replies were actually nego‐
511 tiated on a particular connection use nbd_get_structured_replies_nego‐
512 tiated(3) instead.
513 val get_structured_replies_negotiated : t -> bool
517 see if structured replies are in use
519 After connecting you may call this to find out if the connection is us‐
521 ing structured replies.
522 val set_handshake_flags : t -> HANDSHAKE_FLAG.t list -> unit
526 control use of handshake flags
528 By default, libnbd tries to negotiate all possible handshake flags that
530 are also supported by the server, since omitting a handshake flag can
531 prevent the use of other functionality such as TLS encryption or struc‐
532 tured replies. However, for integration testing, it can be useful to
533 reduce the set of flags supported by the client to test that a particu‐
534 lar server can handle various clients that were compliant to older ver‐
535 sions of the NBD specification.
536 The "flags" argument is a bitmask, including zero or more of the fol‐
538 lowing handshake flags:
539 "LIBNBD_HANDSHAKE_FLAG_FIXED_NEWSTYLE" = 1 The server gracefully han‐
541 dles unknown option requests from the client, rather than disconnect‐
542 ing. Without this flag, a client cannot safely request to use exten‐
543 sions such as TLS encryption or structured replies, as the request may
544 cause an older server to drop the connection.
545 "LIBNBD_HANDSHAKE_FLAG_NO_ZEROES" = 2 If the client is forced to use
547 "NBD_OPT_EXPORT_NAME" instead of the preferred "NBD_OPT_GO", this flag
548 allows the server to send fewer all-zero padding bytes over the connec‐
549 tion.
550 For convenience, the constant "LIBNBD_HANDSHAKE_FLAG_MASK" is available
552 to describe all flags supported by this build of libnbd. Future NBD ex‐
553 tensions may add further flags, which in turn may be enabled by default
554 in newer libnbd. As such, when attempting to disable only one specific
555 bit, it is wiser to first call nbd_get_handshake_flags(3) and modify
556 that value, rather than blindly setting a constant value.
557 val get_handshake_flags : t -> HANDSHAKE_FLAG.t list
561 see which handshake flags are supported
563 Return the state of the handshake flags on this handle. When the han‐
565 dle has not yet completed a connection (see nbd_aio_is_created(3)),
566 this returns the flags that the client is willing to use, provided the
567 server also advertises those flags. After the connection is ready (see
568 nbd_aio_is_ready(3)), this returns the flags that were actually agreed
569 on between the server and client. If the NBD protocol defines new
570 handshake flags, then the return value from a newer library version may
571 include bits that were undefined at the time of compilation.
572 val set_strict_mode : t -> STRICT.t list -> unit
576 control how strictly to follow NBD protocol
578 By default, libnbd tries to detect requests that would trigger unde‐
580 fined behavior in the NBD protocol, and rejects them client side with‐
581 out causing any network traffic, rather than risking undefined server
582 behavior. However, for integration testing, it can be handy to relax
583 the strictness of libnbd, to coerce it into sending such requests over
584 the network for testing the robustness of the server in dealing with
585 such traffic.
586 The "flags" argument is a bitmask, including zero or more of the fol‐
588 lowing strictness flags:
589 "LIBNBD_STRICT_COMMANDS" = 1 If set, this flag rejects client requests
591 that do not comply with the set of advertised server flags (for exam‐
592 ple, attempting a write on a read-only server, or attempting to use
593 "LIBNBD_CMD_FLAG_FUA" when nbd_can_fua(3) returned false). If clear,
594 this flag relies on the server to reject unexpected commands.
595 "LIBNBD_STRICT_FLAGS" = 2 If set, this flag rejects client requests
597 that attempt to set a command flag not recognized by libnbd (those out‐
598 side of "LIBNBD_CMD_FLAG_MASK"), or a flag not normally associated with
599 a command (such as using "LIBNBD_CMD_FLAG_FUA" on a read command). If
600 clear, all flags are sent on to the server, even if sending such a flag
601 may cause the server to change its reply in a manner that confuses
602 libnbd, perhaps causing deadlock or ending the connection.
603 Flags that are known by libnbd as associated with a given command (such
605 as "LIBNBD_CMD_FLAG_DF" for nbd_pread_structured(3) gated by
606 nbd_can_df(3)) are controlled by "LIBNBD_STRICT_COMMANDS" instead.
607 Note that the NBD protocol only supports 16 bits of command flags, even
609 though the libnbd API uses "uint32_t"; bits outside of the range per‐
610 mitted by the protocol are always a client-side error.
611 "LIBNBD_STRICT_BOUNDS" = 3 If set, this flag rejects client requests
613 that would exceed the export bounds without sending any traffic to the
614 server. If clear, this flag relies on the server to detect
615 out-of-bounds requests.
616 "LIBNBD_STRICT_ZERO_SIZE" = 4 If set, this flag rejects client requests
618 with length 0. If clear, this permits zero-length requests to the
619 server, which may produce undefined results.
620 "LIBNBD_STRICT_ALIGN" = 5 If set, and the server provided minimum block
622 sizes (see nbd_get_block_size(3), this flag rejects client requests
623 that do not have length and offset aligned to the server's minimum re‐
624 quirements. If clear, unaligned requests are sent to the server, where
625 it is up to the server whether to honor or reject the request.
626 For convenience, the constant "LIBNBD_STRICT_MASK" is available to de‐
628 scribe all strictness flags supported by this build of libnbd. Future
629 versions of libnbd may add further flags, which are likely to be en‐
630 abled by default for additional client-side filtering. As such, when
631 attempting to relax only one specific bit while keeping remaining
632 checks at the client side, it is wiser to first call
633 nbd_get_strict_mode(3) and modify that value, rather than blindly set‐
634 ting a constant value.
635 val get_strict_mode : t -> STRICT.t list
639 see which strictness flags are in effect
641 Return flags indicating which protocol strictness items are being en‐
643 forced locally by libnbd rather than the server. The return value from
644 a newer library version may include bits that were undefined at the
645 time of compilation.
646 val set_opt_mode : t -> bool -> unit
650 control option mode, for pausing during option negotiation
652 Set this flag to true in order to request that a connection command
654 "nbd_connect_*" will pause for negotiation options rather than proceed‐
655 ing all the way to the ready state, when communicating with a newstyle
656 server. This setting has no effect when connecting to an oldstyle
657 server.
658 When option mode is enabled, you have fine-grained control over which
660 options are negotiated, compared to the default of the server negotiat‐
661 ing everything on your behalf using settings made before starting the
662 connection. To leave the mode and proceed on to the ready state, you
663 must use nbd_opt_go(3) successfully; a failed nbd_opt_go(3) returns to
664 the negotiating state to allow a change of export name before trying
665 again. You may also use nbd_opt_abort(3) to end the connection without
666 finishing negotiation.
667 val get_opt_mode : t -> bool
671 return whether option mode was enabled
673 Return true if option negotiation mode was enabled on this handle.
675 val opt_go : t -> unit
679 end negotiation and move on to using an export
681 Request that the server finish negotiation and move on to serving the
683 export previously specified by the most recent nbd_set_export_name(3)
684 or nbd_connect_uri(3). This can only be used if nbd_set_opt_mode(3)
685 enabled option mode.
686 If this fails, the server may still be in negotiation, where it is pos‐
688 sible to attempt another option such as a different export name; al‐
689 though older servers will instead have killed the connection.
690 val opt_abort : t -> unit
694 end negotiation and close the connection
696 Request that the server finish negotiation, gracefully if possible,
698 then close the connection. This can only be used if nbd_set_opt_mode(3)
699 enabled option mode.
700 val opt_list : t -> (string -> string -> int) -> int
704 request the server to list all exports during negotiation
706 Request that the server list all exports that it supports. This can
708 only be used if nbd_set_opt_mode(3) enabled option mode.
709 The "list" function is called once per advertised export, with any
711 "user_data" passed to this function, and with "name" and "description"
712 supplied by the server. Many servers omit descriptions, in which case
713 "description" will be an empty string. Remember that it is not safe to
714 call nbd_set_export_name(3) from within the context of the callback
715 function; rather, your code must copy any "name" needed for later use
716 after this function completes. At present, the return value of the
717 callback is ignored, although a return of -1 should be avoided.
718 For convenience, when this function succeeds, it returns the number of
720 exports that were advertised by the server.
721 Not all servers understand this request, and even when it is under‐
723 stood, the server might intentionally send an empty list to avoid being
724 an information leak, may encounter a failure after delivering partial
725 results, or may refuse to answer more than one query per connection in
726 the interest of avoiding negotiation that does not resolve. Thus, this
727 function may succeed even when no exports are reported, or may fail but
728 have a non-empty list. Likewise, the NBD protocol does not specify an
729 upper bound for the number of exports that might be advertised, so
730 client code should be aware that a server may send a lengthy list.
731 For nbd-server(1) you will need to allow clients to make list requests
733 by adding "allowlist=true" to the " generic " section of
734 /etc/nbd-server/config. For qemu-nbd(8), a description is set with
735 *-D*.
736 val opt_info : t -> unit
740 request the server for information about an export
742 Request that the server supply information about the export name previ‐
744 ously specified by the most recent nbd_set_export_name(3) or nbd_con‐
745 nect_uri(3). This can only be used if nbd_set_opt_mode(3) enabled op‐
746 tion mode.
747 If successful, functions like nbd_is_read_only(3) and nbd_get_size(3)
749 will report details about that export. In general, if nbd_opt_go(3) is
750 called next, that call will likely succeed with the details remaining
751 the same, although this is not guaranteed by all servers.
752 Not all servers understand this request, and even when it is under‐
754 stood, the server might fail the request even when a corresponding
755 nbd_opt_go(3) would succeed.
756 val opt_list_meta_context : t -> (string -> int) -> int
760 request the server to list available meta contexts
762 Request that the server list available meta contexts associated with
764 the export previously specified by the most recent nbd_set_ex‐
765 port_name(3) or nbd_connect_uri(3). This can only be used if
766 nbd_set_opt_mode(3) enabled option mode.
767 The NBD protocol allows a client to decide how many queries to ask the
769 server. Rather than taking that list of queries as a parameter to this
770 function, libnbd reuses the current list of requested meta contexts as
771 set by nbd_add_meta_context(3); you can use nbd_clear_meta_contexts(3)
772 to set up a different list of queries. When the list is empty, a server
773 will typically reply with all contexts that it supports; when the list
774 is non-empty, the server will reply only with supported contexts that
775 match the client's request. Note that a reply by the server might be
776 encoded to represent several feasible contexts within one string,
777 rather than multiple strings per actual context name that would actu‐
778 ally succeed during nbd_opt_go(3); so it is still necessary to use
779 nbd_can_meta_context(3) after connecting to see which contexts are ac‐
780 tually supported.
781 The "context" function is called once per server reply, with any
783 "user_data" passed to this function, and with "name" supplied by the
784 server. Remember that it is not safe to call nbd_add_meta_context(3)
785 from within the context of the callback function; rather, your code
786 must copy any "name" needed for later use after this function com‐
787 pletes. At present, the return value of the callback is ignored, al‐
788 though a return of -1 should be avoided.
789 For convenience, when this function succeeds, it returns the number of
791 replies returned by the server.
792 Not all servers understand this request, and even when it is under‐
794 stood, the server might intentionally send an empty list because it
795 does not support the requested context, or may encounter a failure af‐
796 ter delivering partial results. Thus, this function may succeed even
797 when no contexts are reported, or may fail but have a non-empty list.
798 Likewise, the NBD protocol does not specify an upper bound for the num‐
799 ber of replies that might be advertised, so client code should be aware
800 that a server may send a lengthy list.
801 val add_meta_context : t -> string -> unit
805 ask server to negotiate metadata context
807 During connection libnbd can negotiate zero or more metadata contexts
809 with the server. Metadata contexts are features (such as "base:alloca‐
810 tion") which describe information returned by the nbd_block_status(3)
811 command (for "base:allocation" this is whether blocks of data are allo‐
812 cated, zero or sparse).
813 This call adds one metadata context to the list to be negotiated. You
815 can call it as many times as needed. The list is initially empty when
816 the handle is created; you can check the contents of the list with
817 nbd_get_nr_meta_contexts(3) and nbd_get_meta_context(3), or clear it
818 with nbd_clear_meta_contexts(3).
819 The NBD protocol limits meta context names to 4096 bytes, but servers
821 may not support the full length. The encoding of meta context names is
822 always UTF-8.
823 Not all servers support all metadata contexts. To learn if a context
825 was actually negotiated, call nbd_can_meta_context(3) after connecting.
826 The single parameter is the name of the metadata context, for example
828 "LIBNBD_CONTEXT_BASE_ALLOCATION". <libnbd.h> includes defined con‐
829 stants beginning with "LIBNBD_CONTEXT_" for some well-known contexts,
830 but you are free to pass in other contexts.
831 Other metadata contexts are server-specific, but include
833 "qemu:dirty-bitmap:..." and "qemu:allocation-depth" for qemu-nbd (see
834 qemu-nbd *-B* and *-A* options).
835 val get_nr_meta_contexts : t -> int
839 return the current number of requested meta contexts
841 During connection libnbd can negotiate zero or more metadata contexts
843 with the server. Metadata contexts are features (such as "base:alloca‐
844 tion") which describe information returned by the nbd_block_status(3)
845 command (for "base:allocation" this is whether blocks of data are allo‐
846 cated, zero or sparse).
847 This command returns how many meta contexts have been added to the list
849 to request from the server via nbd_add_meta_context(3). The server is
850 not obligated to honor all of the requests; to see what it actually
851 supports, see nbd_can_meta_context(3).
852 val get_meta_context : t -> int -> string
856 return the i'th meta context request
858 During connection libnbd can negotiate zero or more metadata contexts
860 with the server. Metadata contexts are features (such as "base:alloca‐
861 tion") which describe information returned by the nbd_block_status(3)
862 command (for "base:allocation" this is whether blocks of data are allo‐
863 cated, zero or sparse).
864 This command returns the i'th meta context request, as added by
866 nbd_add_meta_context(3), and bounded by nbd_get_nr_meta_contexts(3).
867 val clear_meta_contexts : t -> unit
871 reset the list of requested meta contexts
873 During connection libnbd can negotiate zero or more metadata contexts
875 with the server. Metadata contexts are features (such as "base:alloca‐
876 tion") which describe information returned by the nbd_block_status(3)
877 command (for "base:allocation" this is whether blocks of data are allo‐
878 cated, zero or sparse).
879 This command resets the list of meta contexts to request back to an
881 empty list, for re-population by further use of nbd_add_meta_con‐
882 text(3). It is primarily useful when option negotiation mode is se‐
883 lected (see nbd_set_opt_mode(3)), for altering the list of attempted
884 contexts between subsequent export queries.
885 val set_uri_allow_transports : t -> ALLOW_TRANSPORT.t list -> unit
889 set the allowed transports in NBD URIs
891 Set which transports are allowed to appear in NBD URIs. The default is
893 to allow any transport.
894 The "mask" parameter may contain any of the following flags ORed to‐
896 gether:
897 "LIBNBD_ALLOW_TRANSPORT_TCP" "LIBNBD_ALLOW_TRANSPORT_UNIX" "LIBNBD_AL‐
899 LOW_TRANSPORT_VSOCK"
900 For convenience, the constant "LIBNBD_ALLOW_TRANSPORT_MASK" is avail‐
902 able to describe all transports recognized by this build of libnbd. A
903 future version of the library may add new flags.
904 val set_uri_allow_tls : t -> TLS.t -> unit
908 set the allowed TLS settings in NBD URIs
910 Set which TLS settings are allowed to appear in NBD URIs. The default
912 is to allow either non-TLS or TLS URIs.
913 The "tls" parameter can be:
915 "LIBNBD_TLS_DISABLE" TLS URIs are not permitted, ie. a URI such as
917 "nbds://..." will be rejected.
918 "LIBNBD_TLS_ALLOW" This is the default. TLS may be used or not, depend‐
920 ing on whether the URI uses "nbds" or "nbd".
921 "LIBNBD_TLS_REQUIRE" TLS URIs are required. All URIs must use "nbds".
923 val set_uri_allow_local_file : t -> bool -> unit
927 set the allowed transports in NBD URIs
929 Allow NBD URIs to reference local files. This is *disabled* by default.
931 Currently this setting only controls whether the "tls-psk-file" parame‐
933 ter in NBD URIs is allowed.
934 val connect_uri : t -> string -> unit
938 connect to NBD URI
940 Connect (synchronously) to an NBD server and export by specifying the
942 NBD URI. This call parses the URI and calls nbd_set_export_name(3) and
943 nbd_set_tls(3) and other calls as needed, followed by nbd_con‐
944 nect_tcp(3) or nbd_connect_unix(3). However, it is possible to override
945 the export name portion of a URI by using nbd_set_opt_mode(3) to enable
946 option mode, then using nbd_set_export_name(3) and nbd_opt_go(3) as
947 part of subsequent negotiation.
948 This call returns when the connection has been made.
950 Example URIs supported "nbd://example.com" Connect over TCP, unen‐
952 crypted, to "example.com" port 10809.
953 "nbds://example.com" Connect over TCP with TLS, to "example.com" port
955 10809. If the server does not support TLS then this will fail.
956 "nbd+unix:///foo?socket=/tmp/nbd.sock" Connect over the Unix domain
958 socket /tmp/nbd.sock to an NBD server running locally. The export name
959 is set to "foo" (note without any leading "/" character).
960 "nbd+vsock:///" In this scenario libnbd is running in a virtual ma‐
962 chine. Connect over "AF_VSOCK" to an NBD server running on the hypervi‐
963 sor.
964 Supported URI formats The following schemes are supported in the cur‐
966 rent version of libnbd:
967 "nbd:" Connect over TCP without using TLS.
969 "nbds:" Connect over TCP. TLS is required and the connection will fail
971 if the server does not support TLS.
972 "nbd+unix:" "nbds+unix:" Connect over a Unix domain socket, without or
974 with TLS respectively. The "socket" parameter is required.
975 "nbd+vsock:" "nbds+vsock:" Connect over the "AF_VSOCK" transport, with‐
977 out or with TLS respectively.
978 The authority part of the URI (" username@ servername :port ") is
980 parsed depending on the transport. For TCP it specifies the server to
981 connect to and optional port number. For "+unix" it should not be
982 present. For "+vsock" the server name is the numeric CID (eg. 2 to con‐
983 nect to the host), and the optional port number may be present. If the
984 "username" is present it is used for TLS authentication.
985 For all transports, an export name may be present, parsed in accordance
987 with the NBD URI specification.
988 Finally the query part of the URI can contain:
990 socket=SOCKET Specifies the Unix domain socket to connect on. Must be
992 present for the "+unix" transport and must not be present for the other
993 transports.
994 tls-psk-file=PSKFILE Set the PSK file. See nbd_set_tls_psk_file(3).
996 Note this is not allowed by default - see next section.
997 Disable URI features For security reasons you might want to disable
999 certain URI features. Pre-filtering URIs is error-prone and should not
1000 be attempted. Instead use the libnbd APIs below to control what can ap‐
1001 pear in URIs. Note you must call these functions on the same handle be‐
1002 fore calling nbd_connect_uri(3) or nbd_aio_connect_uri(3).
1003 TCP, Unix domain socket or "AF_VSOCK" transports Default: all allowed
1005 To select which transports are allowed call nbd_set_uri_allow_trans‐
1007 ports(3).
1008 TLS Default: both non-TLS and TLS connections allowed
1010 To force TLS off or on in URIs call nbd_set_uri_allow_tls(3).
1012 Connect to Unix domain socket in the local filesystem Default: allowed
1014 To prevent this you must disable the "+unix" transport using
1016 nbd_set_uri_allow_transports(3).
1017 Read from local files Default: denied
1019 To allow URIs to contain references to local files (eg. for parameters
1021 like "tls-psk-file") call nbd_set_uri_allow_local_file(3).
1022 Optional features This call will fail if libnbd was not compiled with
1024 libxml2; you can test whether this is the case with nbd_sup‐
1025 ports_uri(3).
1026 Support for URIs that require TLS will fail if libnbd was not compiled
1028 with gnutls; you can test whether this is the case with nbd_sup‐
1029 ports_tls(3).
1030 Constructing a URI from an existing connection See nbd_get_uri(3).
1032 val connect_unix : t -> string -> unit
1036 connect to NBD server over a Unix domain socket
1038 Connect (synchronously) over the named Unix domain socket ("unix‐
1040 socket") to an NBD server running on the same machine. This call re‐
1041 turns when the connection has been made.
1042 val connect_vsock : t -> int32 -> int32 -> unit
1046 connect to NBD server over AF_VSOCK protocol
1048 Connect (synchronously) over the "AF_VSOCK" protocol from a virtual ma‐
1050 chine to an NBD server, usually running on the host. The "cid" and
1051 "port" parameters specify the server address. Usually "cid" should be 2
1052 (to connect to the host), and "port" might be 10809 or another port
1053 number assigned to you by the host administrator. This call returns
1054 when the connection has been made.
1055 val connect_tcp : t -> string -> string -> unit
1059 connect to NBD server over a TCP port
1061 Connect (synchronously) to the NBD server listening on "hostname:port".
1063 The "port" may be a port name such as "nbd", or it may be a port number
1064 as a string such as "10809". This call returns when the connection has
1065 been made.
1066 val connect_socket : t -> Unix.file_descr -> unit
1070 connect directly to a connected socket
1072 Pass a connected socket "sock" through which libnbd will talk to the
1074 NBD server.
1075 The caller is responsible for creating and connecting this socket by
1077 some method, before passing it to libnbd.
1078 If this call returns without error then socket ownership is passed to
1080 libnbd. Libnbd will close the socket when the handle is closed. The
1081 caller must not use the socket in any way.
1082 val connect_command : t -> string list -> unit
1086 connect to NBD server command
1088 Run the command as a subprocess and connect to it over stdin/stdout.
1090 This is for use with NBD servers which can behave like inetd clients,
1091 such as "nbdkit --single".
1092 Subprocess Libnbd will fork the "argv" command and pass the NBD socket
1094 to it using file descriptors 0 and 1 (stdin/stdout):
1095 ┌─────────┬─────────┐ ┌────────────────┐ │ program │ libnbd │ │
1097 NBD server │ │ │ │ │ (argv) │ │ │
1098 socket ╍╍╍╍╍╍╍╍▶ stdin/stdout │ └─────────┴─────────┘
1099 └────────────────┘
1100 When the NBD handle is closed the server subprocess is killed.
1102 val connect_systemd_socket_activation : t -> string list -> unit
1106 connect using systemd socket activation
1108 Run the command as a subprocess and connect to it using systemd socket
1110 activation.
1111 This is especially useful for running qemu-nbd(1) as a subprocess of
1113 libnbd, for example to use it to open qcow2 files. To run nbdkit as a
1114 subprocess it is usually better to use nbd_connect_command(3).
1115 Socket activation Libnbd will fork the "argv" command and pass an NBD
1117 socket to it using special "LISTEN_*" environment variables (as defined
1118 by the systemd socket activation protocol).
1119 ┌─────────┬─────────┐ ┌───────────────┐ │ program │ libnbd │ │
1121 qemu-nbd or │ │ │ │ │ other server │ │ │
1122 socket ╍╍╍╍╍╍╍╍▶ │ └─────────┴─────────┘
1123 └───────────────┘
1124 When the NBD handle is closed the server subprocess is killed.
1126 val is_read_only : t -> bool
1130 is the NBD export read-only?
1132 Returns true if the NBD export is read-only; writes and write-like op‐
1134 erations will fail.
1135 This call does not block, because it returns data that is saved in the
1137 handle from the NBD protocol handshake.
1138 val can_flush : t -> bool
1142 does the server support the flush command?
1144 Returns true if the server supports the flush command (see
1146 nbd_flush(3), nbd_aio_flush(3)). Returns false if the server does not.
1147 This call does not block, because it returns data that is saved in the
1149 handle from the NBD protocol handshake.
1150 val can_fua : t -> bool
1154 does the server support the FUA flag?
1156 Returns true if the server supports the FUA flag on certain commands
1158 (see nbd_pwrite(3)).
1159 This call does not block, because it returns data that is saved in the
1161 handle from the NBD protocol handshake.
1162 val is_rotational : t -> bool
1166 is the NBD disk rotational (like a disk)?
1168 Returns true if the disk exposed over NBD is rotational (like a tradi‐
1170 tional floppy or hard disk). Returns false if the disk has no penalty
1171 for random access (like an SSD or RAM disk).
1172 This call does not block, because it returns data that is saved in the
1174 handle from the NBD protocol handshake.
1175 val can_trim : t -> bool
1179 does the server support the trim command?
1181 Returns true if the server supports the trim command (see nbd_trim(3),
1183 nbd_aio_trim(3)). Returns false if the server does not.
1184 This call does not block, because it returns data that is saved in the
1186 handle from the NBD protocol handshake.
1187 val can_zero : t -> bool
1191 does the server support the zero command?
1193 Returns true if the server supports the zero command (see nbd_zero(3),
1195 nbd_aio_zero(3)). Returns false if the server does not.
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_fast_zero : t -> bool
1203 does the server support the fast zero flag?
1205 Returns true if the server supports the use of the
1207 "LIBNBD_CMD_FLAG_FAST_ZERO" flag to the zero command (see nbd_zero(3),
1208 nbd_aio_zero(3)). Returns false if the server does not.
1209 This call does not block, because it returns data that is saved in the
1211 handle from the NBD protocol handshake.
1212 val can_df : t -> bool
1216 does the server support the don't fragment flag to pread?
1218 Returns true if the server supports structured reads with an ability to
1220 request a non-fragmented read (see nbd_pread_structured(3),
1221 nbd_aio_pread_structured(3)). Returns false if the server either lacks
1222 structured reads or if it does not support a non-fragmented read re‐
1223 quest.
1224 This call does not block, because it returns data that is saved in the
1226 handle from the NBD protocol handshake.
1227 val can_multi_conn : t -> bool
1231 does the server support multi-conn?
1233 Returns true if the server supports multi-conn. Returns false if the
1235 server does not.
1236 It is not safe to open multiple handles connecting to the same server
1238 if you will write to the server and the server does not advertise
1239 multi-conn support. The safe way to check for this is to open one con‐
1240 nection, check this flag is true, then open further connections as re‐
1241 quired.
1242 This call does not block, because it returns data that is saved in the
1244 handle from the NBD protocol handshake.
1245 val can_cache : t -> bool
1249 does the server support the cache command?
1251 Returns true if the server supports the cache command (see
1253 nbd_cache(3), nbd_aio_cache(3)). Returns false if the server does not.
1254 This call does not block, because it returns data that is saved in the
1256 handle from the NBD protocol handshake.
1257 val can_meta_context : t -> string -> bool
1261 does the server support a specific meta context?
1263 Returns true if the server supports the given meta context (see
1265 nbd_add_meta_context(3)). Returns false if the server does not.
1266 The single parameter is the name of the metadata context, for example
1268 "LIBNBD_CONTEXT_BASE_ALLOCATION". <libnbd.h> includes defined con‐
1269 stants for well-known namespace contexts beginning with "LIBNBD_CON‐
1270 TEXT_", but you are free to pass in other contexts.
1271 This call does not block, because it returns data that is saved in the
1273 handle from the NBD protocol handshake.
1274 val get_protocol : t -> string
1278 return the NBD protocol variant
1280 Return the NBD protocol variant in use on the connection. At the moment
1282 this returns one of the strings "oldstyle", "newstyle" or "new‐
1283 style-fixed". Other strings might be returned in the future. Most mod‐
1284 ern NBD servers use "newstyle-fixed".
1285 This call does not block, because it returns data that is saved in the
1287 handle from the NBD protocol handshake.
1288 val get_size : t -> int64
1292 return the export size
1294 Returns the size in bytes of the NBD export.
1296 This call does not block, because it returns data that is saved in the
1298 handle from the NBD protocol handshake.
1299 val get_block_size : t -> SIZE.t -> int64
1303 return a specific server block size constraint
1305 Returns a specific size constraint advertised by the server, if any. If
1307 the return is zero, the server did not advertise a constraint.
1308 "size_type" must be one of the following constraints:
1309 "LIBNBD_SIZE_MINIMUM" = 0 If non-zero, this will be a power of 2 be‐
1311 tween 1 and 64k; any client request that is not aligned in length or
1312 offset to this size is likely to fail with "EINVAL". The image size
1313 will generally also be a multiple of this value (if not, the final few
1314 bytes are inaccessible while obeying alignment constraints). If zero,
1315 it is safest to assume a minimum block size of 512, although many
1316 servers support a minimum block size of 1. If the server provides a
1317 constraint, then libnbd defaults to honoring that constraint
1318 client-side unless "LIBNBD_STRICT_ALIGN" is cleared in
1319 nbd_set_strict_mode(3).
1320 "LIBNBD_SIZE_PREFERRED" = 1 If non-zero, this is a power of 2 repre‐
1322 senting the preferred size for efficient I/O. Smaller requests may in‐
1323 cur overhead such as read-modify-write cycles that will not be present
1324 when using I/O that is a multiple of this value. This value may be
1325 larger than the size of the export. If zero, using 4k as a preferred
1326 block size tends to give decent performance.
1327 "LIBNBD_SIZE_MAXIMUM" = 2 If non-zero, this represents the maximum
1329 length that the server is willing to handle during nbd_pread(3) or
1330 nbd_pwrite(3). Other functions like nbd_zero(3) may still be able to
1331 use larger sizes. Note that this function returns what the server ad‐
1332 vertised, but libnbd itself imposes a maximum of 64M. If zero, some NBD
1333 servers will abruptly disconnect if a transaction involves more than
1334 32M.
1335 Future NBD extensions may result in additional "size_type" values.
1337 This call does not block, because it returns data that is saved in the
1339 handle from the NBD protocol handshake.
1340 val pread : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 -> unit
1344 read from the NBD server
1346 Issue a read command to the NBD server for the range starting at "off‐
1348 set" and ending at "offset" + "count" - 1. NBD can only read all or
1349 nothing using this call. The call returns when the data has been read
1350 fully into "buf" or there is an error. See also nbd_pread_struc‐
1351 tured(3), if finer visibility is required into the server's replies, or
1352 if you want to use "LIBNBD_CMD_FLAG_DF".
1353 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
1355 tocol extensions).
1356 By default, libnbd will reject attempts to use this function with pa‐
1358 rameters that are likely to result in server failure, such as request‐
1359 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1360 used to alter which scenarios should await a server reply rather than
1361 failing fast.
1362 val pread_structured : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 ->
1366 (bytes -> int64 -> int -> int Stdlib.ref -> int) -> unit
1367 read from the NBD server
1369 Issue a read command to the NBD server for the range starting at "off‐
1371 set" and ending at "offset" + "count" - 1. The server's response may be
1372 subdivided into chunks which may arrive out of order before reassembly
1373 into the original buffer; the "chunk" callback is used for notification
1374 after each chunk arrives, and may perform additional sanity checking on
1375 the server's reply. The callback cannot call "nbd_*" APIs on the same
1376 handle since it holds the handle lock and will cause a deadlock. If the
1377 callback returns -1, and no earlier error has been detected, then the
1378 overall read command will fail with any non-zero value stored into the
1379 callback's "error" parameter (with a default of "EPROTO"); but any fur‐
1380 ther chunks will still invoke the callback.
1381 The "chunk" function is called once per chunk of data received, with
1383 the "user_data" passed to this function. The "subbuf" and "count" pa‐
1384 rameters represent the subset of the original buffer which has just
1385 been populated by results from the server (in C, "subbuf" always points
1386 within the original "buf"; but this guarantee may not extend to other
1387 language bindings). The "offset" parameter represents the absolute off‐
1388 set at which "subbuf" begins within the image (note that this is not
1389 the relative offset of "subbuf" within the original buffer "buf").
1390 Changes to "error" on output are ignored unless the callback fails. The
1391 input meaning of the "error" parameter is controlled by the "status"
1392 parameter, which is one of
1393 "LIBNBD_READ_DATA" = 1 "subbuf" was populated with "count" bytes of
1395 data. On input, "error" contains the errno value of any earlier de‐
1396 tected error, or zero.
1397 "LIBNBD_READ_HOLE" = 2 "subbuf" represents a hole, and contains "count"
1399 NUL bytes. On input, "error" contains the errno value of any earlier
1400 detected error, or zero.
1401 "LIBNBD_READ_ERROR" = 3 "count" is 0, so "subbuf" is unusable. On in‐
1403 put, "error" contains the errno value reported by the server as occur‐
1404 ring while reading that "offset", regardless if any earlier error has
1405 been detected.
1406 Future NBD extensions may permit other values for "status", but those
1408 will not be returned to a client that has not opted in to requesting
1409 such extensions. If the server is non-compliant, it is possible for the
1410 "chunk" function to be called more times than you expect or with
1411 "count" 0 for "LIBNBD_READ_DATA" or "LIBNBD_READ_HOLE". It is also pos‐
1412 sible that the "chunk" function is not called at all (in particular,
1413 "LIBNBD_READ_ERROR" is used only when an error is associated with a
1414 particular offset, and not when the server reports a generic error),
1415 but you are guaranteed that the callback was called at least once if
1416 the overall read succeeds. Libnbd does not validate that the server
1417 obeyed the requirement that a read call must not have overlapping
1418 chunks and must not succeed without enough chunks to cover the entire
1419 request.
1420 The "flags" parameter may be 0 for no flags, or may contain
1422 "LIBNBD_CMD_FLAG_DF" meaning that the server should not reply with more
1423 than one fragment (if that is supported - some servers cannot do this,
1424 see nbd_can_df(3)). Libnbd does not validate that the server actually
1425 obeys the flag.
1426 By default, libnbd will reject attempts to use this function with pa‐
1428 rameters that are likely to result in server failure, such as request‐
1429 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1430 used to alter which scenarios should await a server reply rather than
1431 failing fast.
1432 val pwrite : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 -> unit
1436 write to the NBD server
1438 Issue a write command to the NBD server, writing the data in "buf" to
1440 the range starting at "offset" and ending at "offset" + "count" - 1.
1441 NBD can only write all or nothing using this call. The call returns
1442 when the command has been acknowledged by the server, or there is an
1443 error. Note this will generally return an error if nbd_is_read_only(3)
1444 is true.
1445 The "flags" parameter may be 0 for no flags, or may contain
1447 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
1448 the data has been committed to permanent storage (if that is supported
1449 - some servers cannot do this, see nbd_can_fua(3)).
1450 By default, libnbd will reject attempts to use this function with pa‐
1452 rameters that are likely to result in server failure, such as request‐
1453 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1454 used to alter which scenarios should await a server reply rather than
1455 failing fast.
1456 val shutdown : ?flags:SHUTDOWN.t list -> t -> unit
1460 disconnect from the NBD server
1462 Issue the disconnect command to the NBD server. This is a nice way to
1464 tell the server we are going away, but from the client's point of view
1465 has no advantage over abruptly closing the connection (see
1466 nbd_close(3)).
1467 This function works whether or not the handle is ready for transmission
1469 of commands. If more fine-grained control is needed, see nbd_aio_dis‐
1470 connect(3).
1471 The "flags" argument is a bitmask, including zero or more of the fol‐
1473 lowing shutdown flags:
1474 "LIBNBD_SHUTDOWN_ABANDON_PENDING" = 0x10000 If there are any pending
1476 requests which have not yet been sent to the server (see
1477 nbd_aio_in_flight(3)), abandon them without sending them to the server,
1478 rather than the usual practice of issuing those commands before inform‐
1479 ing the server of the intent to disconnect.
1480 For convenience, the constant "LIBNBD_SHUTDOWN_MASK" is available to
1482 describe all shutdown flags recognized by this build of libnbd. A fu‐
1483 ture version of the library may add new flags.
1484 val flush : ?flags:CMD_FLAG.t list -> t -> unit
1488 send flush command to the NBD server
1490 Issue the flush command to the NBD server. The function should return
1492 when all write commands which have completed have been committed to
1493 permanent storage on the server. Note this will generally return an er‐
1494 ror if nbd_can_flush(3) is false.
1495 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
1497 tocol extensions).
1498 By default, libnbd will reject attempts to use this function with pa‐
1500 rameters that are likely to result in server failure, such as request‐
1501 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1502 used to alter which scenarios should await a server reply rather than
1503 failing fast.
1504 val trim : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
1508 send trim command to the NBD server
1510 Issue a trim command to the NBD server, which if supported by the
1512 server causes a hole to be punched in the backing store starting at
1513 "offset" and ending at "offset" + "count" - 1. The call returns when
1514 the command has been acknowledged by the server, or there is an error.
1515 Note this will generally return an error if nbd_can_trim(3) is false or
1516 nbd_is_read_only(3) is true.
1517 The "flags" parameter may be 0 for no flags, or may contain
1519 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
1520 the data has been committed to permanent storage (if that is supported
1521 - some servers cannot do this, see nbd_can_fua(3)).
1522 By default, libnbd will reject attempts to use this function with pa‐
1524 rameters that are likely to result in server failure, such as request‐
1525 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1526 used to alter which scenarios should await a server reply rather than
1527 failing fast.
1528 val cache : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
1532 send cache (prefetch) command to the NBD server
1534 Issue the cache (prefetch) command to the NBD server, which if sup‐
1536 ported by the server causes data to be prefetched into faster storage
1537 by the server, speeding up a subsequent nbd_pread(3) call. The server
1538 can also silently ignore this command. Note this will generally return
1539 an error if nbd_can_cache(3) is false.
1540 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
1542 tocol extensions).
1543 By default, libnbd will reject attempts to use this function with pa‐
1545 rameters that are likely to result in server failure, such as request‐
1546 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1547 used to alter which scenarios should await a server reply rather than
1548 failing fast.
1549 val zero : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
1553 send write zeroes command to the NBD server
1555 Issue a write zeroes command to the NBD server, which if supported by
1557 the server causes a zeroes to be written efficiently starting at "off‐
1558 set" and ending at "offset"
1559 -"count" - 1. The call returns when the command has been acknowledged
1561 by the server, or there is an error. Note this will generally return
1562 an error if nbd_can_zero(3) is false or nbd_is_read_only(3) is true.
1563 The "flags" parameter may be 0 for no flags, or may contain
1565 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
1566 the data has been committed to permanent storage (if that is supported
1567 - some servers cannot do this, see nbd_can_fua(3)),
1568 "LIBNBD_CMD_FLAG_NO_HOLE" meaning that the server should favor writing
1569 actual allocated zeroes over punching a hole, and/or
1570 "LIBNBD_CMD_FLAG_FAST_ZERO" meaning that the server must fail quickly
1571 if writing zeroes is no faster than a normal write (if that is sup‐
1572 ported - some servers cannot do this, see nbd_can_fast_zero(3)).
1573 By default, libnbd will reject attempts to use this function with pa‐
1575 rameters that are likely to result in server failure, such as request‐
1576 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1577 used to alter which scenarios should await a server reply rather than
1578 failing fast.
1579 val block_status : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 ->
1583 (string -> int64 -> int32 array -> int Stdlib.ref -> int) -> unit
1584 send block status command to the NBD server
1586 Issue the block status command to the NBD server. If supported by the
1588 server, this causes metadata context information about blocks beginning
1589 from the specified offset to be returned. The "count" parameter is a
1590 hint: the server may choose to return less status, or the final block
1591 may extend beyond the requested range. If multiple contexts are sup‐
1592 ported, the number of blocks and cumulative length of those blocks need
1593 not be identical between contexts.
1594 Depending on which metadata contexts were enabled before connecting
1596 (see nbd_add_meta_context(3)) and which are supported by the server
1597 (see nbd_can_meta_context(3)) this call returns information about ex‐
1598 tents by calling back to the "extent" function. The callback cannot
1599 call "nbd_*" APIs on the same handle since it holds the handle lock and
1600 will cause a deadlock. If the callback returns -1, and no earlier error
1601 has been detected, then the overall block status command will fail with
1602 any non-zero value stored into the callback's "error" parameter (with a
1603 default of "EPROTO"); but any further contexts will still invoke the
1604 callback.
1605 The "extent" function is called once per type of metadata available,
1607 with the "user_data" passed to this function. The "metacontext" parame‐
1608 ter is a string such as "base:allocation". The "entries" array is an
1609 array of pairs of integers with the first entry in each pair being the
1610 length (in bytes) of the block and the second entry being a sta‐
1611 tus/flags field which is specific to the metadata context. (The number
1612 of pairs passed to the function is "nr_entries/2".) The NBD protocol
1613 document in the section about "NBD_REPLY_TYPE_BLOCK_STATUS" describes
1614 the meaning of this array; for contexts known to libnbd, <libnbd.h>
1615 contains constants beginning with "LIBNBD_STATE_" that may help deci‐
1616 pher the values. On entry to the callback, the "error" parameter con‐
1617 tains the errno value of any previously detected error.
1618 It is possible for the extent function to be called more times than you
1620 expect (if the server is buggy), so always check the "metacontext"
1621 field to ensure you are receiving the data you expect. It is also pos‐
1622 sible that the extent function is not called at all, even for metadata
1623 contexts that you requested. This indicates either that the server
1624 doesn't support the context or for some other reason cannot return the
1625 data.
1626 The "flags" parameter may be 0 for no flags, or may contain
1628 "LIBNBD_CMD_FLAG_REQ_ONE" meaning that the server should return only
1629 one extent per metadata context where that extent does not exceed
1630 "count" bytes; however, libnbd does not validate that the server obeyed
1631 the flag.
1632 By default, libnbd will reject attempts to use this function with pa‐
1634 rameters that are likely to result in server failure, such as request‐
1635 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1636 used to alter which scenarios should await a server reply rather than
1637 failing fast.
1638 val poll : t -> int -> int
1642 poll the handle once
1644 This is a simple implementation of poll(2) which is used internally by
1646 synchronous API calls. On success, it returns 0 if the "timeout" (in
1647 milliseconds) occurs, or 1 if the poll completed and the state machine
1648 progressed. Set "timeout" to -1 to block indefinitely (but be careful
1649 that eventual action is actually expected - for example, if the connec‐
1650 tion is established but there are no commands in flight, using an infi‐
1651 nite timeout will permanently block).
1652 This function is mainly useful as an example of how you might integrate
1654 libnbd with your own main loop, rather than being intended as something
1655 you would use.
1656 val aio_connect : t -> string -> unit
1660 connect to the NBD server
1662 Begin connecting to the NBD server. The "addr" and "addrlen" parameters
1664 specify the address of the socket to connect to.
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_uri : t -> string -> unit
1674 connect to an NBD URI
1676 Begin connecting to the NBD URI "uri". Parameters behave as documented
1678 in nbd_connect_uri(3).
1679 You can check if the connection is still connecting by calling
1681 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1682 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1683 tion.
1684 val aio_connect_unix : t -> string -> unit
1688 connect to the NBD server over a Unix domain socket
1690 Begin connecting to the NBD server over Unix domain socket ("unix‐
1692 socket"). Parameters behave as documented in nbd_connect_unix(3).
1693 You can check if the connection is still connecting by calling
1695 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1696 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1697 tion.
1698 val aio_connect_vsock : t -> int32 -> int32 -> unit
1702 connect to the NBD server over AF_VSOCK socket
1704 Begin connecting to the NBD server over the "AF_VSOCK" protocol to the
1706 server "cid:port". Parameters behave as documented in nbd_con‐
1707 nect_vsock(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_tcp : t -> string -> string -> unit
1717 connect to the NBD server over a TCP port
1719 Begin connecting to the NBD server listening on "hostname:port". Param‐
1721 eters behave as documented in nbd_connect_tcp(3).
1722 You can check if the connection is still connecting by calling
1724 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1725 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1726 tion.
1727 val aio_connect_socket : t -> Unix.file_descr -> unit
1731 connect directly to a connected socket
1733 Begin connecting to the connected socket "fd". Parameters behave as
1735 documented in nbd_connect_socket(3).
1736 You can check if the connection is still connecting by calling
1738 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1739 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1740 tion.
1741 val aio_connect_command : t -> string list -> unit
1745 connect to the NBD server
1747 Run the command as a subprocess and begin connecting to it over
1749 stdin/stdout. Parameters behave as documented in nbd_connect_com‐
1750 mand(3).
1751 You can check if the connection is still connecting by calling
1753 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1754 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1755 tion.
1756 val aio_connect_systemd_socket_activation : t -> string list -> unit
1760 connect using systemd socket activation
1762 Run the command as a subprocess and begin connecting to it using sys‐
1764 temd socket activation. Parameters behave as documented in nbd_con‐
1765 nect_systemd_socket_activation(3).
1766 You can check if the connection is still connecting by calling
1768 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1769 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1770 tion.
1771 val aio_opt_go : ?completion:(int Stdlib.ref -> int) -> t -> unit
1775 end negotiation and move on to using an export
1777 Request that the server finish negotiation and move on to serving the
1779 export previously specified by the most recent nbd_set_export_name(3)
1780 or nbd_connect_uri(3). This can only be used if nbd_set_opt_mode(3)
1781 enabled option mode.
1782 To determine when the request completes, wait for nbd_aio_is_connect‐
1784 ing(3) to return false. Or supply the optional "completion_callback"
1785 which will be invoked as described in "Completion callbacks" in
1786 libnbd(3), except that it is automatically retired regardless of return
1787 value. Note that directly detecting whether the server returns an error
1788 (as is done by the return value of the synchronous counterpart) is only
1789 possible with a completion callback; however it is also possible to in‐
1790 directly detect an error when nbd_aio_is_negotiating(3) returns true.
1791 val aio_opt_abort : t -> unit
1795 end negotiation and close the connection
1797 Request that the server finish negotiation, gracefully if possible,
1799 then close the connection. This can only be used if nbd_set_opt_mode(3)
1800 enabled option mode.
1801 To determine when the request completes, wait for nbd_aio_is_connect‐
1803 ing(3) to return false.
1804 val aio_opt_list : ?completion:(int Stdlib.ref -> int) -> t -> (string
1808 -> string -> int) -> unit
1809 request the server to list all exports during negotiation
1811 Request that the server list all exports that it supports. This can
1813 only be used if nbd_set_opt_mode(3) enabled option mode.
1814 To determine when the request completes, wait for nbd_aio_is_connect‐
1816 ing(3) to return false. Or supply the optional "completion_callback"
1817 which will be invoked as described in "Completion callbacks" in
1818 libnbd(3), except that it is automatically retired regardless of return
1819 value. Note that detecting whether the server returns an error (as is
1820 done by the return value of the synchronous counterpart) is only possi‐
1821 ble with a completion callback.
1822 val aio_opt_info : ?completion:(int Stdlib.ref -> int) -> t -> unit
1826 request the server for information about an export
1828 Request that the server supply information about the export name previ‐
1830 ously specified by the most recent nbd_set_export_name(3) or nbd_con‐
1831 nect_uri(3). This can only be used if nbd_set_opt_mode(3) enabled op‐
1832 tion mode.
1833 To determine when the request completes, wait for nbd_aio_is_connect‐
1835 ing(3) to return false. Or supply the optional "completion_callback"
1836 which will be invoked as described in "Completion callbacks" in
1837 libnbd(3), except that it is automatically retired regardless of return
1838 value. Note that detecting whether the server returns an error (as is
1839 done by the return value of the synchronous counterpart) is only possi‐
1840 ble with a completion callback.
1841 val aio_opt_list_meta_context : ?completion:(int Stdlib.ref -> int) ->
1845 t -> (string -> int) -> int
1846 request the server to list available meta contexts
1848 Request that the server list available meta contexts associated with
1850 the export previously specified by the most recent nbd_set_ex‐
1851 port_name(3) or nbd_connect_uri(3). This can only be used if
1852 nbd_set_opt_mode(3) enabled option mode.
1853 To determine when the request completes, wait for nbd_aio_is_connect‐
1855 ing(3) to return false. Or supply the optional "completion_callback"
1856 which will be invoked as described in "Completion callbacks" in
1857 libnbd(3), except that it is automatically retired regardless of return
1858 value. Note that detecting whether the server returns an error (as is
1859 done by the return value of the synchronous counterpart) is only possi‐
1860 ble with a completion callback.
1861 val aio_pread : ?completion:(int Stdlib.ref -> int) ->
1865 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> cookie
1866 read from the NBD server
1868 Issue a read command to the NBD server.
1870 To check if the command completed, call nbd_aio_command_completed(3).
1872 Or supply the optional "completion_callback" which will be invoked as
1873 described in "Completion callbacks" in libnbd(3).
1874 Note that you must ensure "buf" is valid until the command has com‐
1876 pleted. Other parameters behave as documented in nbd_pread(3).
1877 By default, libnbd will reject attempts to use this function with pa‐
1879 rameters that are likely to result in server failure, such as request‐
1880 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1881 used to alter which scenarios should await a server reply rather than
1882 failing fast.
1883 val aio_pread_structured : ?completion:(int Stdlib.ref -> int) ->
1887 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> (bytes -> int64 ->
1888 int -> int Stdlib.ref -> int) -> cookie
1889 read from the NBD server
1891 Issue a read command to the NBD server.
1893 To check if the command completed, call nbd_aio_command_completed(3).
1895 Or supply the optional "completion_callback" which will be invoked as
1896 described in "Completion callbacks" in libnbd(3).
1897 Other parameters behave as documented in nbd_pread_structured(3).
1899 By default, libnbd will reject attempts to use this function with pa‐
1901 rameters that are likely to result in server failure, such as request‐
1902 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1903 used to alter which scenarios should await a server reply rather than
1904 failing fast.
1905 val aio_pwrite : ?completion:(int Stdlib.ref -> int) ->
1909 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> cookie
1910 write to the NBD server
1912 Issue a write command to the NBD server.
1914 To check if the command completed, call nbd_aio_command_completed(3).
1916 Or supply the optional "completion_callback" which will be invoked as
1917 described in "Completion callbacks" in libnbd(3).
1918 Note that you must ensure "buf" is valid until the command has com‐
1920 pleted. Other parameters behave as documented in nbd_pwrite(3).
1921 By default, libnbd will reject attempts to use this function with pa‐
1923 rameters that are likely to result in server failure, such as request‐
1924 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1925 used to alter which scenarios should await a server reply rather than
1926 failing fast.
1927 val aio_disconnect : ?flags:CMD_FLAG.t list -> t -> unit
1931 disconnect from the NBD server
1933 Issue the disconnect command to the NBD server. This is not a normal
1935 command because NBD servers are not obliged to send a reply. Instead
1936 you should wait for nbd_aio_is_closed(3) to become true on the connec‐
1937 tion. Once this command is issued, you cannot issue any further com‐
1938 mands.
1939 Although libnbd does not prevent you from issuing this command while
1941 still waiting on the replies to previous commands, the NBD protocol
1942 recommends that you wait until there are no other commands in flight
1943 (see nbd_aio_in_flight(3)), to give the server a better chance at a
1944 clean shutdown.
1945 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
1947 tocol extensions). There is no direct synchronous counterpart; however,
1948 nbd_shutdown(3) will call this function if appropriate.
1949 val aio_flush : ?completion:(int Stdlib.ref -> int) ->
1953 ?flags:CMD_FLAG.t list -> t -> cookie
1954 send flush command to the NBD server
1956 Issue the flush command to the NBD server.
1958 To check if the command completed, call nbd_aio_command_completed(3).
1960 Or supply the optional "completion_callback" which will be invoked as
1961 described in "Completion callbacks" in libnbd(3).
1962 Other parameters behave as documented in nbd_flush(3).
1964 By default, libnbd will reject attempts to use this function with pa‐
1966 rameters that are likely to result in server failure, such as request‐
1967 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1968 used to alter which scenarios should await a server reply rather than
1969 failing fast.
1970 val aio_trim : ?completion:(int Stdlib.ref -> int) -> ?flags:CMD_FLAG.t
1974 list -> t -> int64 -> int64 -> cookie
1975 send trim command to the NBD server
1977 Issue a trim command to the NBD server.
1979 To check if the command completed, call nbd_aio_command_completed(3).
1981 Or supply the optional "completion_callback" which will be invoked as
1982 described in "Completion callbacks" in libnbd(3).
1983 Other parameters behave as documented in nbd_trim(3).
1985 By default, libnbd will reject attempts to use this function with pa‐
1987 rameters that are likely to result in server failure, such as request‐
1988 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1989 used to alter which scenarios should await a server reply rather than
1990 failing fast.
1991 val aio_cache : ?completion:(int Stdlib.ref -> int) ->
1995 ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> cookie
1996 send cache (prefetch) command to the NBD server
1998 Issue the cache (prefetch) command to the NBD server.
2000 To check if the command completed, call nbd_aio_command_completed(3).
2002 Or supply the optional "completion_callback" which will be invoked as
2003 described in "Completion callbacks" in libnbd(3).
2004 Other parameters behave as documented in nbd_cache(3).
2006 By default, libnbd will reject attempts to use this function with pa‐
2008 rameters that are likely to result in server failure, such as request‐
2009 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2010 used to alter which scenarios should await a server reply rather than
2011 failing fast.
2012 val aio_zero : ?completion:(int Stdlib.ref -> int) -> ?flags:CMD_FLAG.t
2016 list -> t -> int64 -> int64 -> cookie
2017 send write zeroes command to the NBD server
2019 Issue a write zeroes command to the NBD server.
2021 To check if the command completed, call nbd_aio_command_completed(3).
2023 Or supply the optional "completion_callback" which will be invoked as
2024 described in "Completion callbacks" in libnbd(3).
2025 Other parameters behave as documented in nbd_zero(3).
2027 By default, libnbd will reject attempts to use this function with pa‐
2029 rameters that are likely to result in server failure, such as request‐
2030 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2031 used to alter which scenarios should await a server reply rather than
2032 failing fast.
2033 val aio_block_status : ?completion:(int Stdlib.ref -> int) ->
2037 ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> (string -> int64 ->
2038 int32 array -> int Stdlib.ref -> int) -> cookie
2039 send block status command to the NBD server
2041 Send the block status command to the NBD server.
2043 To check if the command completed, call nbd_aio_command_completed(3).
2045 Or supply the optional "completion_callback" which will be invoked as
2046 described in "Completion callbacks" in libnbd(3).
2047 Other parameters behave as documented in nbd_block_status(3).
2049 By default, libnbd will reject attempts to use this function with pa‐
2051 rameters that are likely to result in server failure, such as request‐
2052 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2053 used to alter which scenarios should await a server reply rather than
2054 failing fast.
2055 val aio_get_fd : t -> Unix.file_descr
2059 return file descriptor associated with this connection
2061 Return the underlying file descriptor associated with this connection.
2063 You can use this to check if the file descriptor is ready for reading
2064 or writing and call nbd_aio_notify_read(3) or nbd_aio_notify_write(3).
2065 See also nbd_aio_get_direction(3). Do not do anything else with the
2066 file descriptor.
2067 val aio_get_direction : t -> int
2071 return the read or write direction
2073 Return the current direction of this connection, which means whether we
2075 are next expecting to read data from the server, write data to the
2076 server, or both. It returns
2077 0 We are not expected to interact with the server file descriptor
2079 from the current state. It is not worth attempting to use poll(2); if
2080 the connection is not dead, then state machine progress must instead
2081 come from some other means such as nbd_aio_connect(3).
2082 "LIBNBD_AIO_DIRECTION_READ" = 1 We are expected next to read from the
2084 server. If using poll(2) you would set "events = POLLIN". If "revents"
2085 returns "POLLIN" or "POLLHUP" you would then call nbd_aio_no‐
2086 tify_read(3).
2087 Note that once libnbd reaches nbd_aio_is_ready(3), this direction is
2089 returned even when there are no commands in flight (see
2090 nbd_aio_in_flight(3)). In a single-threaded use of libnbd, it is not
2091 worth polling until after issuing a command, as otherwise the server
2092 will never wake up the poll. In a multi-threaded scenario, you can have
2093 one thread begin a polling loop prior to any commands, but any other
2094 thread that issues a command will need a way to kick the polling thread
2095 out of poll in case issuing the command changes the needed polling di‐
2096 rection. Possible ways to do this include polling for activity on a
2097 pipe-to-self, or using pthread_kill(3) to send a signal that is masked
2098 except during ppoll(2).
2099 "LIBNBD_AIO_DIRECTION_WRITE" = 2 We are expected next to write to the
2101 server. If using poll(2) you would set "events = POLLOUT". If "revents"
2102 returns "POLLOUT" you would then call nbd_aio_notify_write(3).
2103 "LIBNBD_AIO_DIRECTION_BOTH" = 3 We are expected next to either read or
2105 write to the server. If using poll(2) you would set "events =
2106 POLLIN|POLLOUT". If only one of "POLLIN" or "POLLOUT" is returned, then
2107 see above. However, if both are returned, it is better to call only
2108 nbd_aio_notify_read(3), as processing the server's reply may change the
2109 state of the connection and invalidate the need to write more commands.
2110 val aio_notify_read : t -> unit
2114 notify that the connection is readable
2116 Send notification to the state machine that the connection is readable.
2118 Typically this is called after your main loop has detected that the
2119 file descriptor associated with this connection is readable.
2120 val aio_notify_write : t -> unit
2124 notify that the connection is writable
2126 Send notification to the state machine that the connection is writable.
2128 Typically this is called after your main loop has detected that the
2129 file descriptor associated with this connection is writable.
2130 val aio_is_created : t -> bool
2134 check if the connection has just been created
2136 Return true if this connection has just been created. This is the
2138 state before the handle has started connecting to a server. In this
2139 state the handle can start to be connected by calling functions such as
2140 nbd_aio_connect(3).
2141 val aio_is_connecting : t -> bool
2145 check if the connection is connecting or handshaking
2147 Return true if this connection is connecting to the server or in the
2149 process of handshaking and negotiating options which happens before the
2150 handle becomes ready to issue commands (see nbd_aio_is_ready(3)).
2151 val aio_is_negotiating : t -> bool
2155 check if connection is ready to send handshake option
2157 Return true if this connection is ready to start another option negoti‐
2159 ation command while handshaking with the server. An option command will
2160 move back to the connecting state (see nbd_aio_is_connecting(3)). Note
2161 that this state cannot be reached unless requested by
2162 nbd_set_opt_mode(3), and even then it only works with newstyle servers;
2163 an oldstyle server will skip straight to nbd_aio_is_ready(3).
2164 val aio_is_ready : t -> bool
2168 check if the connection is in the ready state
2170 Return true if this connection is connected to the NBD server, the
2172 handshake has completed, and the connection is idle or waiting for a
2173 reply. In this state the handle is ready to issue commands.
2174 val aio_is_processing : t -> bool
2178 check if the connection is processing a command
2180 Return true if this connection is connected to the NBD server, the
2182 handshake has completed, and the connection is processing commands (ei‐
2183 ther writing out a request or reading a reply).
2184 Note the ready state (nbd_aio_is_ready(3)) is not included. In the
2186 ready state commands may be *in flight* (the *server* is processing
2187 them), but libnbd is not processing them.
2188 val aio_is_dead : t -> bool
2192 check if the connection is dead
2194 Return true if the connection has encountered a fatal error and is
2196 dead. In this state the handle may only be closed. There is no way to
2197 recover a handle from the dead state.
2198 val aio_is_closed : t -> bool
2202 check if the connection is closed
2204 Return true if the connection has closed. There is no way to reconnect
2206 a closed connection. Instead you must close the whole handle.
2207 val aio_command_completed : t -> int64 -> bool
2211 check if the command completed
2213 Return true if the command completed. If this function returns true
2215 then the command was successful and it has been retired. Return false
2216 if the command is still in flight. This can also fail with an error in
2217 case the command failed (in this case the command is also retired). A
2218 command is retired either via this command, or by using a completion
2219 callback which returns 1.
2220 The "cookie" parameter is the positive unique 64 bit cookie for the
2222 command, as returned by a call such as nbd_aio_pread(3).
2223 val aio_peek_command_completed : t -> int64
2227 check if any command has completed
2229 Return the unique positive 64 bit cookie of the first non-retired but
2231 completed command, 0 if there are in-flight commands but none of them
2232 are awaiting retirement, or -1 on error including when there are no
2233 in-flight commands. Any cookie returned by this function must still be
2234 passed to nbd_aio_command_completed(3) to actually retire the command
2235 and learn whether the command was successful.
2236 val aio_in_flight : t -> int
2240 check how many aio commands are still in flight
2242 Return the number of in-flight aio commands that are still awaiting a
2244 response from the server before they can be retired. If this returns a
2245 non-zero value when requesting a disconnect from the server (see
2246 nbd_aio_disconnect(3) and nbd_shutdown(3)), libnbd does not try to wait
2247 for those commands to complete gracefully; if the server strands com‐
2248 mands while shutting down, nbd_aio_command_completed(3) will report
2249 those commands as failed with a status of "ENOTCONN".
2250 val connection_state : t -> string
2254 return string describing the state of the connection
2256 Returns a descriptive string for the state of the connection. This can
2258 be used for debugging or troubleshooting, but you should not rely on
2259 the state of connections since it may change in future versions.
2260 val get_package_name : t -> string
2264 return the name of the library
2266 Returns the name of the library, always "libnbd" unless the library was
2268 modified with another name at compile time.
2269 val get_version : t -> string
2273 return the version of the library
2275 Return the version of libnbd. This is returned as a string in the form
2277 "major.minor.release" where each of major, minor and release is a small
2278 positive integer. For example:
2279 minor ↓ "1.0.3" ↑ ↑ major release
2281 major = 0 The major number was 0 for the early experimental versions of
2283 libnbd where we still had an unstable API.
2284 major = 1 The major number is 1 for the versions of libnbd with a
2286 long-term stable API and ABI. It is not anticipated that major will be
2287 any number other than 1.
2288 minor = 0, 2, ... (even) The minor number is even for stable releases.
2290 minor = 1, 3, ... (odd) The minor number is odd for development ver‐
2292 sions. Note that new APIs added in a development version remain exper‐
2293 imental and subject to change in that branch until they appear in a
2294 stable release.
2295 release The release number is incremented for each release along a par‐
2297 ticular branch.
2298 val kill_subprocess : t -> int -> unit
2302 kill server running as a subprocess
2304 This call may be used to kill the server running as a subprocess that
2306 was previously created using nbd_connect_command(3). You do not need to
2307 use this call. It is only needed if the server does not exit when the
2308 socket is closed.
2309 The "signum" parameter is the optional signal number to send (see sig‐
2311 nal(7)). If "signum" is 0 then "SIGTERM" is sent.
2312 val supports_tls : t -> bool
2316 true if libnbd was compiled with support for TLS
2318 Returns true if libnbd was compiled with gnutls which is required to
2320 support TLS encryption, or false if not.
2321 val supports_uri : t -> bool
2325 true if libnbd was compiled with support for NBD URIs
2327 Returns true if libnbd was compiled with libxml2 which is required to
2329 support NBD URIs, or false if not.
2330 val get_uri : t -> string
2334 construct an NBD URI for a connection
2336 This makes a best effort attempt to construct an NBD URI which could be
2338 used to connect back to the same server (using nbd_connect_uri(3)).
2339 In some cases there is not enough information in the handle to success‐
2341 fully create a URI (eg. if you connected with nbd_connect_socket(3)).
2342 In such cases the call returns "NULL" and further diagnostic informa‐
2343 tion is available via nbd_get_errno(3) and nbd_get_error(3) as usual.
2344 Even if a URI is returned it is not guaranteed to work, and it may not
2346 be optimal.
2347OCamldoc 2021-05-29 NBD(3)