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).
945 This call returns when the connection has been made.
947 Example URIs supported "nbd://example.com" Connect over TCP, unen‐
949 crypted, to "example.com" port 10809.
950 "nbds://example.com" Connect over TCP with TLS, to "example.com" port
952 10809. If the server does not support TLS then this will fail.
953 "nbd+unix:///foo?socket=/tmp/nbd.sock" Connect over the Unix domain
955 socket /tmp/nbd.sock to an NBD server running locally. The export name
956 is set to "foo" (note without any leading "/" character).
957 "nbds+unix://alice@/?socket=/tmp/nbd.sock&tls-certificat es=certs" Con‐
959 nect over a Unix domain socket, enabling TLS and setting the path to a
960 directory containing certificates and keys.
961 "nbd+vsock:///" In this scenario libnbd is running in a virtual ma‐
963 chine. Connect over "AF_VSOCK" to an NBD server running on the hypervi‐
964 sor.
965 Supported URI formats The following schemes are supported in the cur‐
967 rent version of libnbd:
968 "nbd:" Connect over TCP without using TLS.
970 "nbds:" Connect over TCP. TLS is required and the connection will fail
972 if the server does not support TLS.
973 "nbd+unix:" "nbds+unix:" Connect over a Unix domain socket, without or
975 with TLS respectively. The "socket" parameter is required.
976 "nbd+vsock:" "nbds+vsock:" Connect over the "AF_VSOCK" transport, with‐
978 out or with TLS respectively.
979 The authority part of the URI (" username@ servername :port ") is
981 parsed depending on the transport. For TCP it specifies the server to
982 connect to and optional port number. For "+unix" it should not be
983 present. For "+vsock" the server name is the numeric CID (eg. 2 to con‐
984 nect to the host), and the optional port number may be present. If the
985 "username" is present it is used for TLS authentication.
986 For all transports, an export name may be present, parsed in accordance
988 with the NBD URI specification.
989 Finally the query part of the URI can contain:
991 socket=SOCKET Specifies the Unix domain socket to connect on. Must be
993 present for the "+unix" transport and must not be present for the other
994 transports.
995 tls-certificates=DIR Set the certificates directory. See
997 nbd_set_tls_certificates(3). Note this is not allowed by default - see
998 next section.
999 tls-psk-file=PSKFILE Set the PSK file. See nbd_set_tls_psk_file(3).
1001 Note this is not allowed by default - see next section.
1002 Disable URI features For security reasons you might want to disable
1004 certain URI features. Pre-filtering URIs is error-prone and should not
1005 be attempted. Instead use the libnbd APIs below to control what can ap‐
1006 pear in URIs. Note you must call these functions on the same handle be‐
1007 fore calling nbd_connect_uri(3) or nbd_aio_connect_uri(3).
1008 TCP, Unix domain socket or "AF_VSOCK" transports Default: all allowed
1010 To select which transports are allowed call nbd_set_uri_allow_trans‐
1012 ports(3).
1013 TLS Default: both non-TLS and TLS connections allowed
1015 To force TLS off or on in URIs call nbd_set_uri_allow_tls(3).
1017 Connect to Unix domain socket in the local filesystem Default: allowed
1019 To prevent this you must disable the "+unix" transport using
1021 nbd_set_uri_allow_transports(3).
1022 Read from local files Default: denied
1024 To allow URIs to contain references to local files (eg. for parameters
1026 like "tls-psk-file") call nbd_set_uri_allow_local_file(3).
1027 Overriding the export name It is possible to override the export name
1029 portion of a URI by using nbd_set_opt_mode(3) to enable option mode,
1030 then using nbd_set_export_name(3) and nbd_opt_go(3) as part of subse‐
1031 quent negotiation.
1032 Optional features This call will fail if libnbd was not compiled with
1034 libxml2; you can test whether this is the case with nbd_sup‐
1035 ports_uri(3).
1036 Support for URIs that require TLS will fail if libnbd was not compiled
1038 with gnutls; you can test whether this is the case with nbd_sup‐
1039 ports_tls(3).
1040 Constructing a URI from an existing connection See nbd_get_uri(3).
1042 val connect_unix : t -> string -> unit
1046 connect to NBD server over a Unix domain socket
1048 Connect (synchronously) over the named Unix domain socket ("unix‐
1050 socket") to an NBD server running on the same machine. This call re‐
1051 turns when the connection has been made.
1052 val connect_vsock : t -> int32 -> int32 -> unit
1056 connect to NBD server over AF_VSOCK protocol
1058 Connect (synchronously) over the "AF_VSOCK" protocol from a virtual ma‐
1060 chine to an NBD server, usually running on the host. The "cid" and
1061 "port" parameters specify the server address. Usually "cid" should be 2
1062 (to connect to the host), and "port" might be 10809 or another port
1063 number assigned to you by the host administrator. This call returns
1064 when the connection has been made.
1065 val connect_tcp : t -> string -> string -> unit
1069 connect to NBD server over a TCP port
1071 Connect (synchronously) to the NBD server listening on "hostname:port".
1073 The "port" may be a port name such as "nbd", or it may be a port number
1074 as a string such as "10809". This call returns when the connection has
1075 been made.
1076 val connect_socket : t -> Unix.file_descr -> unit
1080 connect directly to a connected socket
1082 Pass a connected socket "sock" through which libnbd will talk to the
1084 NBD server.
1085 The caller is responsible for creating and connecting this socket by
1087 some method, before passing it to libnbd.
1088 If this call returns without error then socket ownership is passed to
1090 libnbd. Libnbd will close the socket when the handle is closed. The
1091 caller must not use the socket in any way.
1092 val connect_command : t -> string list -> unit
1096 connect to NBD server command
1098 Run the command as a subprocess and connect to it over stdin/stdout.
1100 This is for use with NBD servers which can behave like inetd clients,
1101 such as nbdkit(1) using the *-s*/*--single* flag, and nbd-server(1)
1102 with port number set to 0.
1103 To run qemu-nbd(1), use nbd_connect_systemd_socket_activation(3) in‐
1105 stead.
1106 Subprocess Libnbd will fork the "argv" command and pass the NBD socket
1108 to it using file descriptors 0 and 1 (stdin/stdout):
1109 ┌─────────┬─────────┐ ┌────────────────┐ │ program │ libnbd │ │
1111 NBD server │ │ │ │ │ (argv) │ │ │
1112 socket ╍╍╍╍╍╍╍╍▶ stdin/stdout │ └─────────┴─────────┘
1113 └────────────────┘
1114 When the NBD handle is closed the server subprocess is killed.
1116 val connect_systemd_socket_activation : t -> string list -> unit
1120 connect using systemd socket activation
1122 Run the command as a subprocess and connect to it using systemd socket
1124 activation.
1125 This is especially useful for running qemu-nbd(1) as a subprocess of
1127 libnbd, for example to use it to open qcow2 files.
1128 To run nbdkit as a subprocess, this function can be used, or nbd_con‐
1130 nect_command(3).
1131 To run nbd-server(1) as a subprocess, this function cannot be used, you
1133 must use nbd_connect_command(3).
1134 Socket activation Libnbd will fork the "argv" command and pass an NBD
1136 socket to it using special "LISTEN_*" environment variables (as defined
1137 by the systemd socket activation protocol).
1138 ┌─────────┬─────────┐ ┌───────────────┐ │ program │ libnbd │ │
1140 qemu-nbd or │ │ │ │ │ other server │ │ │
1141 socket ╍╍╍╍╍╍╍╍▶ │ └─────────┴─────────┘
1142 └───────────────┘
1143 When the NBD handle is closed the server subprocess is killed.
1145 val is_read_only : t -> bool
1149 is the NBD export read-only?
1151 Returns true if the NBD export is read-only; writes and write-like op‐
1153 erations will fail.
1154 This call does not block, because it returns data that is saved in the
1156 handle from the NBD protocol handshake.
1157 val can_flush : t -> bool
1161 does the server support the flush command?
1163 Returns true if the server supports the flush command (see
1165 nbd_flush(3), nbd_aio_flush(3)). Returns false if the server does not.
1166 This call does not block, because it returns data that is saved in the
1168 handle from the NBD protocol handshake.
1169 val can_fua : t -> bool
1173 does the server support the FUA flag?
1175 Returns true if the server supports the FUA flag on certain commands
1177 (see nbd_pwrite(3)).
1178 This call does not block, because it returns data that is saved in the
1180 handle from the NBD protocol handshake.
1181 val is_rotational : t -> bool
1185 is the NBD disk rotational (like a disk)?
1187 Returns true if the disk exposed over NBD is rotational (like a tradi‐
1189 tional floppy or hard disk). Returns false if the disk has no penalty
1190 for random access (like an SSD or RAM disk).
1191 This call does not block, because it returns data that is saved in the
1193 handle from the NBD protocol handshake.
1194 val can_trim : t -> bool
1198 does the server support the trim command?
1200 Returns true if the server supports the trim command (see nbd_trim(3),
1202 nbd_aio_trim(3)). Returns false if the server does not.
1203 This call does not block, because it returns data that is saved in the
1205 handle from the NBD protocol handshake.
1206 val can_zero : t -> bool
1210 does the server support the zero command?
1212 Returns true if the server supports the zero command (see nbd_zero(3),
1214 nbd_aio_zero(3)). Returns false if the server does not.
1215 This call does not block, because it returns data that is saved in the
1217 handle from the NBD protocol handshake.
1218 val can_fast_zero : t -> bool
1222 does the server support the fast zero flag?
1224 Returns true if the server supports the use of the
1226 "LIBNBD_CMD_FLAG_FAST_ZERO" flag to the zero command (see nbd_zero(3),
1227 nbd_aio_zero(3)). Returns false if the server does not.
1228 This call does not block, because it returns data that is saved in the
1230 handle from the NBD protocol handshake.
1231 val can_df : t -> bool
1235 does the server support the don't fragment flag to pread?
1237 Returns true if the server supports structured reads with an ability to
1239 request a non-fragmented read (see nbd_pread_structured(3),
1240 nbd_aio_pread_structured(3)). Returns false if the server either lacks
1241 structured reads or if it does not support a non-fragmented read re‐
1242 quest.
1243 This call does not block, because it returns data that is saved in the
1245 handle from the NBD protocol handshake.
1246 val can_multi_conn : t -> bool
1250 does the server support multi-conn?
1252 Returns true if the server supports multi-conn. Returns false if the
1254 server does not.
1255 It is not safe to open multiple handles connecting to the same server
1257 if you will write to the server and the server does not advertise
1258 multi-conn support. The safe way to check for this is to open one con‐
1259 nection, check this flag is true, then open further connections as re‐
1260 quired.
1261 This call does not block, because it returns data that is saved in the
1263 handle from the NBD protocol handshake.
1264 val can_cache : t -> bool
1268 does the server support the cache command?
1270 Returns true if the server supports the cache command (see
1272 nbd_cache(3), nbd_aio_cache(3)). Returns false if the server does not.
1273 This call does not block, because it returns data that is saved in the
1275 handle from the NBD protocol handshake.
1276 val can_meta_context : t -> string -> bool
1280 does the server support a specific meta context?
1282 Returns true if the server supports the given meta context (see
1284 nbd_add_meta_context(3)). Returns false if the server does not.
1285 The single parameter is the name of the metadata context, for example
1287 "LIBNBD_CONTEXT_BASE_ALLOCATION". <libnbd.h> includes defined con‐
1288 stants for well-known namespace contexts beginning with "LIBNBD_CON‐
1289 TEXT_", but you are free to pass in other contexts.
1290 This call does not block, because it returns data that is saved in the
1292 handle from the NBD protocol handshake.
1293 val get_protocol : t -> string
1297 return the NBD protocol variant
1299 Return the NBD protocol variant in use on the connection. At the moment
1301 this returns one of the strings "oldstyle", "newstyle" or "new‐
1302 style-fixed". Other strings might be returned in the future. Most mod‐
1303 ern NBD servers use "newstyle-fixed".
1304 This call does not block, because it returns data that is saved in the
1306 handle from the NBD protocol handshake.
1307 val get_size : t -> int64
1311 return the export size
1313 Returns the size in bytes of the NBD export.
1315 This call does not block, because it returns data that is saved in the
1317 handle from the NBD protocol handshake.
1318 val get_block_size : t -> SIZE.t -> int64
1322 return a specific server block size constraint
1324 Returns a specific size constraint advertised by the server, if any. If
1326 the return is zero, the server did not advertise a constraint.
1327 "size_type" must be one of the following constraints:
1328 "LIBNBD_SIZE_MINIMUM" = 0 If non-zero, this will be a power of 2 be‐
1330 tween 1 and 64k; any client request that is not aligned in length or
1331 offset to this size is likely to fail with "EINVAL". The image size
1332 will generally also be a multiple of this value (if not, the final few
1333 bytes are inaccessible while obeying alignment constraints). If zero,
1334 it is safest to assume a minimum block size of 512, although many
1335 servers support a minimum block size of 1. If the server provides a
1336 constraint, then libnbd defaults to honoring that constraint
1337 client-side unless "LIBNBD_STRICT_ALIGN" is cleared in
1338 nbd_set_strict_mode(3).
1339 "LIBNBD_SIZE_PREFERRED" = 1 If non-zero, this is a power of 2 repre‐
1341 senting the preferred size for efficient I/O. Smaller requests may in‐
1342 cur overhead such as read-modify-write cycles that will not be present
1343 when using I/O that is a multiple of this value. This value may be
1344 larger than the size of the export. If zero, using 4k as a preferred
1345 block size tends to give decent performance.
1346 "LIBNBD_SIZE_MAXIMUM" = 2 If non-zero, this represents the maximum
1348 length that the server is willing to handle during nbd_pread(3) or
1349 nbd_pwrite(3). Other functions like nbd_zero(3) may still be able to
1350 use larger sizes. Note that this function returns what the server ad‐
1351 vertised, but libnbd itself imposes a maximum of 64M. If zero, some NBD
1352 servers will abruptly disconnect if a transaction involves more than
1353 32M.
1354 Future NBD extensions may result in additional "size_type" values.
1356 This call does not block, because it returns data that is saved in the
1358 handle from the NBD protocol handshake.
1359 val pread : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 -> unit
1363 read from the NBD server
1365 Issue a read command to the NBD server for the range starting at "off‐
1367 set" and ending at "offset" + "count" - 1. NBD can only read all or
1368 nothing using this call. The call returns when the data has been read
1369 fully into "buf" or there is an error. See also nbd_pread_struc‐
1370 tured(3), if finer visibility is required into the server's replies, or
1371 if you want to use "LIBNBD_CMD_FLAG_DF".
1372 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
1374 tocol extensions).
1375 By default, libnbd will reject attempts to use this function with pa‐
1377 rameters that are likely to result in server failure, such as request‐
1378 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1379 used to alter which scenarios should await a server reply rather than
1380 failing fast.
1381 val pread_structured : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 ->
1385 (bytes -> int64 -> int -> int Stdlib.ref -> int) -> unit
1386 read from the NBD server
1388 Issue a read command to the NBD server for the range starting at "off‐
1390 set" and ending at "offset" + "count" - 1. The server's response may be
1391 subdivided into chunks which may arrive out of order before reassembly
1392 into the original buffer; the "chunk" callback is used for notification
1393 after each chunk arrives, and may perform additional sanity checking on
1394 the server's reply. The callback cannot call "nbd_*" APIs on the same
1395 handle since it holds the handle lock and will cause a deadlock. If the
1396 callback returns -1, and no earlier error has been detected, then the
1397 overall read command will fail with any non-zero value stored into the
1398 callback's "error" parameter (with a default of "EPROTO"); but any fur‐
1399 ther chunks will still invoke the callback.
1400 The "chunk" function is called once per chunk of data received, with
1402 the "user_data" passed to this function. The "subbuf" and "count" pa‐
1403 rameters represent the subset of the original buffer which has just
1404 been populated by results from the server (in C, "subbuf" always points
1405 within the original "buf"; but this guarantee may not extend to other
1406 language bindings). The "offset" parameter represents the absolute off‐
1407 set at which "subbuf" begins within the image (note that this is not
1408 the relative offset of "subbuf" within the original buffer "buf").
1409 Changes to "error" on output are ignored unless the callback fails. The
1410 input meaning of the "error" parameter is controlled by the "status"
1411 parameter, which is one of
1412 "LIBNBD_READ_DATA" = 1 "subbuf" was populated with "count" bytes of
1414 data. On input, "error" contains the errno value of any earlier de‐
1415 tected error, or zero.
1416 "LIBNBD_READ_HOLE" = 2 "subbuf" represents a hole, and contains "count"
1418 NUL bytes. On input, "error" contains the errno value of any earlier
1419 detected error, or zero.
1420 "LIBNBD_READ_ERROR" = 3 "count" is 0, so "subbuf" is unusable. On in‐
1422 put, "error" contains the errno value reported by the server as occur‐
1423 ring while reading that "offset", regardless if any earlier error has
1424 been detected.
1425 Future NBD extensions may permit other values for "status", but those
1427 will not be returned to a client that has not opted in to requesting
1428 such extensions. If the server is non-compliant, it is possible for the
1429 "chunk" function to be called more times than you expect or with
1430 "count" 0 for "LIBNBD_READ_DATA" or "LIBNBD_READ_HOLE". It is also pos‐
1431 sible that the "chunk" function is not called at all (in particular,
1432 "LIBNBD_READ_ERROR" is used only when an error is associated with a
1433 particular offset, and not when the server reports a generic error),
1434 but you are guaranteed that the callback was called at least once if
1435 the overall read succeeds. Libnbd does not validate that the server
1436 obeyed the requirement that a read call must not have overlapping
1437 chunks and must not succeed without enough chunks to cover the entire
1438 request.
1439 The "flags" parameter may be 0 for no flags, or may contain
1441 "LIBNBD_CMD_FLAG_DF" meaning that the server should not reply with more
1442 than one fragment (if that is supported - some servers cannot do this,
1443 see nbd_can_df(3)). Libnbd does not validate that the server actually
1444 obeys the flag.
1445 By default, libnbd will reject attempts to use this function with pa‐
1447 rameters that are likely to result in server failure, such as request‐
1448 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1449 used to alter which scenarios should await a server reply rather than
1450 failing fast.
1451 val pwrite : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 -> unit
1455 write to the NBD server
1457 Issue a write command to the NBD server, writing the data in "buf" to
1459 the range starting at "offset" and ending at "offset" + "count" - 1.
1460 NBD can only write all or nothing using this call. The call returns
1461 when the command has been acknowledged by the server, or there is an
1462 error. Note this will generally return an error if nbd_is_read_only(3)
1463 is true.
1464 The "flags" parameter may be 0 for no flags, or may contain
1466 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
1467 the data has been committed to permanent storage (if that is supported
1468 - some servers cannot do this, see nbd_can_fua(3)).
1469 By default, libnbd will reject attempts to use this function with pa‐
1471 rameters that are likely to result in server failure, such as request‐
1472 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1473 used to alter which scenarios should await a server reply rather than
1474 failing fast.
1475 val shutdown : ?flags:SHUTDOWN.t list -> t -> unit
1479 disconnect from the NBD server
1481 Issue the disconnect command to the NBD server. This is a nice way to
1483 tell the server we are going away, but from the client's point of view
1484 has no advantage over abruptly closing the connection (see
1485 nbd_close(3)).
1486 This function works whether or not the handle is ready for transmission
1488 of commands. If more fine-grained control is needed, see nbd_aio_dis‐
1489 connect(3).
1490 The "flags" argument is a bitmask, including zero or more of the fol‐
1492 lowing shutdown flags:
1493 "LIBNBD_SHUTDOWN_ABANDON_PENDING" = 0x10000 If there are any pending
1495 requests which have not yet been sent to the server (see
1496 nbd_aio_in_flight(3)), abandon them without sending them to the server,
1497 rather than the usual practice of issuing those commands before inform‐
1498 ing the server of the intent to disconnect.
1499 For convenience, the constant "LIBNBD_SHUTDOWN_MASK" is available to
1501 describe all shutdown flags recognized by this build of libnbd. A fu‐
1502 ture version of the library may add new flags.
1503 val flush : ?flags:CMD_FLAG.t list -> t -> unit
1507 send flush command to the NBD server
1509 Issue the flush command to the NBD server. The function should return
1511 when all write commands which have completed have been committed to
1512 permanent storage on the server. Note this will generally return an er‐
1513 ror if nbd_can_flush(3) is false.
1514 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
1516 tocol extensions).
1517 By default, libnbd will reject attempts to use this function with pa‐
1519 rameters that are likely to result in server failure, such as request‐
1520 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1521 used to alter which scenarios should await a server reply rather than
1522 failing fast.
1523 val trim : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
1527 send trim command to the NBD server
1529 Issue a trim command to the NBD server, which if supported by the
1531 server causes a hole to be punched in the backing store starting at
1532 "offset" and ending at "offset" + "count" - 1. The call returns when
1533 the command has been acknowledged by the server, or there is an error.
1534 Note this will generally return an error if nbd_can_trim(3) is false or
1535 nbd_is_read_only(3) is true.
1536 The "flags" parameter may be 0 for no flags, or may contain
1538 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
1539 the data has been committed to permanent storage (if that is supported
1540 - some servers cannot do this, see nbd_can_fua(3)).
1541 By default, libnbd will reject attempts to use this function with pa‐
1543 rameters that are likely to result in server failure, such as request‐
1544 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1545 used to alter which scenarios should await a server reply rather than
1546 failing fast.
1547 val cache : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
1551 send cache (prefetch) command to the NBD server
1553 Issue the cache (prefetch) command to the NBD server, which if sup‐
1555 ported by the server causes data to be prefetched into faster storage
1556 by the server, speeding up a subsequent nbd_pread(3) call. The server
1557 can also silently ignore this command. Note this will generally return
1558 an error if nbd_can_cache(3) is false.
1559 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
1561 tocol extensions).
1562 By default, libnbd will reject attempts to use this function with pa‐
1564 rameters that are likely to result in server failure, such as request‐
1565 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1566 used to alter which scenarios should await a server reply rather than
1567 failing fast.
1568 val zero : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
1572 send write zeroes command to the NBD server
1574 Issue a write zeroes command to the NBD server, which if supported by
1576 the server causes a zeroes to be written efficiently starting at "off‐
1577 set" and ending at "offset"
1578 -"count" - 1. The call returns when the command has been acknowledged
1580 by the server, or there is an error. Note this will generally return
1581 an error if nbd_can_zero(3) is false or nbd_is_read_only(3) is true.
1582 The "flags" parameter may be 0 for no flags, or may contain
1584 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
1585 the data has been committed to permanent storage (if that is supported
1586 - some servers cannot do this, see nbd_can_fua(3)),
1587 "LIBNBD_CMD_FLAG_NO_HOLE" meaning that the server should favor writing
1588 actual allocated zeroes over punching a hole, and/or
1589 "LIBNBD_CMD_FLAG_FAST_ZERO" meaning that the server must fail quickly
1590 if writing zeroes is no faster than a normal write (if that is sup‐
1591 ported - some servers cannot do this, see nbd_can_fast_zero(3)).
1592 By default, libnbd will reject attempts to use this function with pa‐
1594 rameters that are likely to result in server failure, such as request‐
1595 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1596 used to alter which scenarios should await a server reply rather than
1597 failing fast.
1598 val block_status : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 ->
1602 (string -> int64 -> int32 array -> int Stdlib.ref -> int) -> unit
1603 send block status command to the NBD server
1605 Issue the block status command to the NBD server. If supported by the
1607 server, this causes metadata context information about blocks beginning
1608 from the specified offset to be returned. The "count" parameter is a
1609 hint: the server may choose to return less status, or the final block
1610 may extend beyond the requested range. If multiple contexts are sup‐
1611 ported, the number of blocks and cumulative length of those blocks need
1612 not be identical between contexts.
1613 Depending on which metadata contexts were enabled before connecting
1615 (see nbd_add_meta_context(3)) and which are supported by the server
1616 (see nbd_can_meta_context(3)) this call returns information about ex‐
1617 tents by calling back to the "extent" function. The callback cannot
1618 call "nbd_*" APIs on the same handle since it holds the handle lock and
1619 will cause a deadlock. If the callback returns -1, and no earlier error
1620 has been detected, then the overall block status command will fail with
1621 any non-zero value stored into the callback's "error" parameter (with a
1622 default of "EPROTO"); but any further contexts will still invoke the
1623 callback.
1624 The "extent" function is called once per type of metadata available,
1626 with the "user_data" passed to this function. The "metacontext" parame‐
1627 ter is a string such as "base:allocation". The "entries" array is an
1628 array of pairs of integers with the first entry in each pair being the
1629 length (in bytes) of the block and the second entry being a sta‐
1630 tus/flags field which is specific to the metadata context. (The number
1631 of pairs passed to the function is "nr_entries/2".) The NBD protocol
1632 document in the section about "NBD_REPLY_TYPE_BLOCK_STATUS" describes
1633 the meaning of this array; for contexts known to libnbd, <libnbd.h>
1634 contains constants beginning with "LIBNBD_STATE_" that may help deci‐
1635 pher the values. On entry to the callback, the "error" parameter con‐
1636 tains the errno value of any previously detected error.
1637 It is possible for the extent function to be called more times than you
1639 expect (if the server is buggy), so always check the "metacontext"
1640 field to ensure you are receiving the data you expect. It is also pos‐
1641 sible that the extent function is not called at all, even for metadata
1642 contexts that you requested. This indicates either that the server
1643 doesn't support the context or for some other reason cannot return the
1644 data.
1645 The "flags" parameter may be 0 for no flags, or may contain
1647 "LIBNBD_CMD_FLAG_REQ_ONE" meaning that the server should return only
1648 one extent per metadata context where that extent does not exceed
1649 "count" bytes; however, libnbd does not validate that the server obeyed
1650 the flag.
1651 By default, libnbd will reject attempts to use this function with pa‐
1653 rameters that are likely to result in server failure, such as request‐
1654 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1655 used to alter which scenarios should await a server reply rather than
1656 failing fast.
1657 val poll : t -> int -> int
1661 poll the handle once
1663 This is a simple implementation of poll(2) which is used internally by
1665 synchronous API calls. On success, it returns 0 if the "timeout" (in
1666 milliseconds) occurs, or 1 if the poll completed and the state machine
1667 progressed. Set "timeout" to -1 to block indefinitely (but be careful
1668 that eventual action is actually expected - for example, if the connec‐
1669 tion is established but there are no commands in flight, using an infi‐
1670 nite timeout will permanently block).
1671 This function is mainly useful as an example of how you might integrate
1673 libnbd with your own main loop, rather than being intended as something
1674 you would use.
1675 val aio_connect : t -> string -> unit
1679 connect to the NBD server
1681 Begin connecting to the NBD server. The "addr" and "addrlen" parameters
1683 specify the address of the socket to connect to.
1684 You can check if the connection is still connecting by calling
1686 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1687 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1688 tion.
1689 val aio_connect_uri : t -> string -> unit
1693 connect to an NBD URI
1695 Begin connecting to the NBD URI "uri". Parameters behave as documented
1697 in nbd_connect_uri(3).
1698 You can check if the connection is still connecting by calling
1700 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1701 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1702 tion.
1703 val aio_connect_unix : t -> string -> unit
1707 connect to the NBD server over a Unix domain socket
1709 Begin connecting to the NBD server over Unix domain socket ("unix‐
1711 socket"). Parameters behave as documented in nbd_connect_unix(3).
1712 You can check if the connection is still connecting by calling
1714 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1715 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1716 tion.
1717 val aio_connect_vsock : t -> int32 -> int32 -> unit
1721 connect to the NBD server over AF_VSOCK socket
1723 Begin connecting to the NBD server over the "AF_VSOCK" protocol to the
1725 server "cid:port". Parameters behave as documented in nbd_con‐
1726 nect_vsock(3).
1727 You can check if the connection is still connecting by calling
1729 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1730 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1731 tion.
1732 val aio_connect_tcp : t -> string -> string -> unit
1736 connect to the NBD server over a TCP port
1738 Begin connecting to the NBD server listening on "hostname:port". Param‐
1740 eters behave as documented in nbd_connect_tcp(3).
1741 You can check if the connection is still connecting by calling
1743 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1744 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1745 tion.
1746 val aio_connect_socket : t -> Unix.file_descr -> unit
1750 connect directly to a connected socket
1752 Begin connecting to the connected socket "fd". Parameters behave as
1754 documented in nbd_connect_socket(3).
1755 You can check if the connection is still connecting by calling
1757 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1758 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1759 tion.
1760 val aio_connect_command : t -> string list -> unit
1764 connect to the NBD server
1766 Run the command as a subprocess and begin connecting to it over
1768 stdin/stdout. Parameters behave as documented in nbd_connect_com‐
1769 mand(3).
1770 You can check if the connection is still connecting by calling
1772 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1773 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1774 tion.
1775 val aio_connect_systemd_socket_activation : t -> string list -> unit
1779 connect using systemd socket activation
1781 Run the command as a subprocess and begin connecting to it using sys‐
1783 temd socket activation. Parameters behave as documented in nbd_con‐
1784 nect_systemd_socket_activation(3).
1785 You can check if the connection is still connecting by calling
1787 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1788 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1789 tion.
1790 val aio_opt_go : ?completion:(int Stdlib.ref -> int) -> t -> unit
1794 end negotiation and move on to using an export
1796 Request that the server finish negotiation and move on to serving the
1798 export previously specified by the most recent nbd_set_export_name(3)
1799 or nbd_connect_uri(3). 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. Or supply the optional "completion_callback"
1804 which will be invoked as described in "Completion callbacks" in
1805 libnbd(3), except that it is automatically retired regardless of return
1806 value. Note that directly detecting whether the server returns an error
1807 (as is done by the return value of the synchronous counterpart) is only
1808 possible with a completion callback; however it is also possible to in‐
1809 directly detect an error when nbd_aio_is_negotiating(3) returns true.
1810 val aio_opt_abort : t -> unit
1814 end negotiation and close the connection
1816 Request that the server finish negotiation, gracefully if possible,
1818 then close the connection. This can only be used if nbd_set_opt_mode(3)
1819 enabled option mode.
1820 To determine when the request completes, wait for nbd_aio_is_connect‐
1822 ing(3) to return false.
1823 val aio_opt_list : ?completion:(int Stdlib.ref -> int) -> t -> (string
1827 -> string -> int) -> unit
1828 request the server to list all exports during negotiation
1830 Request that the server list all exports that it supports. This can
1832 only be used if nbd_set_opt_mode(3) enabled option 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_info : ?completion:(int Stdlib.ref -> int) -> t -> unit
1845 request the server for information about an export
1847 Request that the server supply information about the export name previ‐
1849 ously specified by the most recent nbd_set_export_name(3) or nbd_con‐
1850 nect_uri(3). This can only be used if nbd_set_opt_mode(3) enabled op‐
1851 tion mode.
1852 To determine when the request completes, wait for nbd_aio_is_connect‐
1854 ing(3) to return false. Or supply the optional "completion_callback"
1855 which will be invoked as described in "Completion callbacks" in
1856 libnbd(3), except that it is automatically retired regardless of return
1857 value. Note that detecting whether the server returns an error (as is
1858 done by the return value of the synchronous counterpart) is only possi‐
1859 ble with a completion callback.
1860 val aio_opt_list_meta_context : ?completion:(int Stdlib.ref -> int) ->
1864 t -> (string -> int) -> int
1865 request the server to list available meta contexts
1867 Request that the server list available meta contexts associated with
1869 the export previously specified by the most recent nbd_set_ex‐
1870 port_name(3) or nbd_connect_uri(3). This can only be used if
1871 nbd_set_opt_mode(3) enabled option mode.
1872 To determine when the request completes, wait for nbd_aio_is_connect‐
1874 ing(3) to return false. Or supply the optional "completion_callback"
1875 which will be invoked as described in "Completion callbacks" in
1876 libnbd(3), except that it is automatically retired regardless of return
1877 value. Note that detecting whether the server returns an error (as is
1878 done by the return value of the synchronous counterpart) is only possi‐
1879 ble with a completion callback.
1880 val aio_pread : ?completion:(int Stdlib.ref -> int) ->
1884 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> cookie
1885 read from the NBD server
1887 Issue a read command to the NBD server.
1889 To check if the command completed, call nbd_aio_command_completed(3).
1891 Or supply the optional "completion_callback" which will be invoked as
1892 described in "Completion callbacks" in libnbd(3).
1893 Note that you must ensure "buf" is valid until the command has com‐
1895 pleted. Other parameters behave as documented in nbd_pread(3).
1896 By default, libnbd will reject attempts to use this function with pa‐
1898 rameters that are likely to result in server failure, such as request‐
1899 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1900 used to alter which scenarios should await a server reply rather than
1901 failing fast.
1902 val aio_pread_structured : ?completion:(int Stdlib.ref -> int) ->
1906 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> (bytes -> int64 ->
1907 int -> int Stdlib.ref -> int) -> cookie
1908 read from the NBD server
1910 Issue a read command to the NBD server.
1912 To check if the command completed, call nbd_aio_command_completed(3).
1914 Or supply the optional "completion_callback" which will be invoked as
1915 described in "Completion callbacks" in libnbd(3).
1916 Other parameters behave as documented in nbd_pread_structured(3).
1918 By default, libnbd will reject attempts to use this function with pa‐
1920 rameters that are likely to result in server failure, such as request‐
1921 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1922 used to alter which scenarios should await a server reply rather than
1923 failing fast.
1924 val aio_pwrite : ?completion:(int Stdlib.ref -> int) ->
1928 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> cookie
1929 write to the NBD server
1931 Issue a write command to the NBD server.
1933 To check if the command completed, call nbd_aio_command_completed(3).
1935 Or supply the optional "completion_callback" which will be invoked as
1936 described in "Completion callbacks" in libnbd(3).
1937 Note that you must ensure "buf" is valid until the command has com‐
1939 pleted. Other parameters behave as documented in nbd_pwrite(3).
1940 By default, libnbd will reject attempts to use this function with pa‐
1942 rameters that are likely to result in server failure, such as request‐
1943 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1944 used to alter which scenarios should await a server reply rather than
1945 failing fast.
1946 val aio_disconnect : ?flags:CMD_FLAG.t list -> t -> unit
1950 disconnect from the NBD server
1952 Issue the disconnect command to the NBD server. This is not a normal
1954 command because NBD servers are not obliged to send a reply. Instead
1955 you should wait for nbd_aio_is_closed(3) to become true on the connec‐
1956 tion. Once this command is issued, you cannot issue any further com‐
1957 mands.
1958 Although libnbd does not prevent you from issuing this command while
1960 still waiting on the replies to previous commands, the NBD protocol
1961 recommends that you wait until there are no other commands in flight
1962 (see nbd_aio_in_flight(3)), to give the server a better chance at a
1963 clean shutdown.
1964 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
1966 tocol extensions). There is no direct synchronous counterpart; however,
1967 nbd_shutdown(3) will call this function if appropriate.
1968 val aio_flush : ?completion:(int Stdlib.ref -> int) ->
1972 ?flags:CMD_FLAG.t list -> t -> cookie
1973 send flush command to the NBD server
1975 Issue the flush command to the NBD server.
1977 To check if the command completed, call nbd_aio_command_completed(3).
1979 Or supply the optional "completion_callback" which will be invoked as
1980 described in "Completion callbacks" in libnbd(3).
1981 Other parameters behave as documented in nbd_flush(3).
1983 By default, libnbd will reject attempts to use this function with pa‐
1985 rameters that are likely to result in server failure, such as request‐
1986 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1987 used to alter which scenarios should await a server reply rather than
1988 failing fast.
1989 val aio_trim : ?completion:(int Stdlib.ref -> int) -> ?flags:CMD_FLAG.t
1993 list -> t -> int64 -> int64 -> cookie
1994 send trim command to the NBD server
1996 Issue a trim command to the NBD server.
1998 To check if the command completed, call nbd_aio_command_completed(3).
2000 Or supply the optional "completion_callback" which will be invoked as
2001 described in "Completion callbacks" in libnbd(3).
2002 Other parameters behave as documented in nbd_trim(3).
2004 By default, libnbd will reject attempts to use this function with pa‐
2006 rameters that are likely to result in server failure, such as request‐
2007 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2008 used to alter which scenarios should await a server reply rather than
2009 failing fast.
2010 val aio_cache : ?completion:(int Stdlib.ref -> int) ->
2014 ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> cookie
2015 send cache (prefetch) command to the NBD server
2017 Issue the cache (prefetch) command to the NBD server.
2019 To check if the command completed, call nbd_aio_command_completed(3).
2021 Or supply the optional "completion_callback" which will be invoked as
2022 described in "Completion callbacks" in libnbd(3).
2023 Other parameters behave as documented in nbd_cache(3).
2025 By default, libnbd will reject attempts to use this function with pa‐
2027 rameters that are likely to result in server failure, such as request‐
2028 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2029 used to alter which scenarios should await a server reply rather than
2030 failing fast.
2031 val aio_zero : ?completion:(int Stdlib.ref -> int) -> ?flags:CMD_FLAG.t
2035 list -> t -> int64 -> int64 -> cookie
2036 send write zeroes command to the NBD server
2038 Issue a write zeroes command to the NBD server.
2040 To check if the command completed, call nbd_aio_command_completed(3).
2042 Or supply the optional "completion_callback" which will be invoked as
2043 described in "Completion callbacks" in libnbd(3).
2044 Other parameters behave as documented in nbd_zero(3).
2046 By default, libnbd will reject attempts to use this function with pa‐
2048 rameters that are likely to result in server failure, such as request‐
2049 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2050 used to alter which scenarios should await a server reply rather than
2051 failing fast.
2052 val aio_block_status : ?completion:(int Stdlib.ref -> int) ->
2056 ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> (string -> int64 ->
2057 int32 array -> int Stdlib.ref -> int) -> cookie
2058 send block status command to the NBD server
2060 Send the block status command to the NBD server.
2062 To check if the command completed, call nbd_aio_command_completed(3).
2064 Or supply the optional "completion_callback" which will be invoked as
2065 described in "Completion callbacks" in libnbd(3).
2066 Other parameters behave as documented in nbd_block_status(3).
2068 By default, libnbd will reject attempts to use this function with pa‐
2070 rameters that are likely to result in server failure, such as request‐
2071 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2072 used to alter which scenarios should await a server reply rather than
2073 failing fast.
2074 val aio_get_fd : t -> Unix.file_descr
2078 return file descriptor associated with this connection
2080 Return the underlying file descriptor associated with this connection.
2082 You can use this to check if the file descriptor is ready for reading
2083 or writing and call nbd_aio_notify_read(3) or nbd_aio_notify_write(3).
2084 See also nbd_aio_get_direction(3). Do not do anything else with the
2085 file descriptor.
2086 val aio_get_direction : t -> int
2090 return the read or write direction
2092 Return the current direction of this connection, which means whether we
2094 are next expecting to read data from the server, write data to the
2095 server, or both. It returns
2096 0 We are not expected to interact with the server file descriptor
2098 from the current state. It is not worth attempting to use poll(2); if
2099 the connection is not dead, then state machine progress must instead
2100 come from some other means such as nbd_aio_connect(3).
2101 "LIBNBD_AIO_DIRECTION_READ" = 1 We are expected next to read from the
2103 server. If using poll(2) you would set "events = POLLIN". If "revents"
2104 returns "POLLIN" or "POLLHUP" you would then call nbd_aio_no‐
2105 tify_read(3).
2106 Note that once libnbd reaches nbd_aio_is_ready(3), this direction is
2108 returned even when there are no commands in flight (see
2109 nbd_aio_in_flight(3)). In a single-threaded use of libnbd, it is not
2110 worth polling until after issuing a command, as otherwise the server
2111 will never wake up the poll. In a multi-threaded scenario, you can have
2112 one thread begin a polling loop prior to any commands, but any other
2113 thread that issues a command will need a way to kick the polling thread
2114 out of poll in case issuing the command changes the needed polling di‐
2115 rection. Possible ways to do this include polling for activity on a
2116 pipe-to-self, or using pthread_kill(3) to send a signal that is masked
2117 except during ppoll(2).
2118 "LIBNBD_AIO_DIRECTION_WRITE" = 2 We are expected next to write to the
2120 server. If using poll(2) you would set "events = POLLOUT". If "revents"
2121 returns "POLLOUT" you would then call nbd_aio_notify_write(3).
2122 "LIBNBD_AIO_DIRECTION_BOTH" = 3 We are expected next to either read or
2124 write to the server. If using poll(2) you would set "events =
2125 POLLIN|POLLOUT". If only one of "POLLIN" or "POLLOUT" is returned, then
2126 see above. However, if both are returned, it is better to call only
2127 nbd_aio_notify_read(3), as processing the server's reply may change the
2128 state of the connection and invalidate the need to write more commands.
2129 val aio_notify_read : t -> unit
2133 notify that the connection is readable
2135 Send notification to the state machine that the connection is readable.
2137 Typically this is called after your main loop has detected that the
2138 file descriptor associated with this connection is readable.
2139 val aio_notify_write : t -> unit
2143 notify that the connection is writable
2145 Send notification to the state machine that the connection is writable.
2147 Typically this is called after your main loop has detected that the
2148 file descriptor associated with this connection is writable.
2149 val aio_is_created : t -> bool
2153 check if the connection has just been created
2155 Return true if this connection has just been created. This is the
2157 state before the handle has started connecting to a server. In this
2158 state the handle can start to be connected by calling functions such as
2159 nbd_aio_connect(3).
2160 val aio_is_connecting : t -> bool
2164 check if the connection is connecting or handshaking
2166 Return true if this connection is connecting to the server or in the
2168 process of handshaking and negotiating options which happens before the
2169 handle becomes ready to issue commands (see nbd_aio_is_ready(3)).
2170 val aio_is_negotiating : t -> bool
2174 check if connection is ready to send handshake option
2176 Return true if this connection is ready to start another option negoti‐
2178 ation command while handshaking with the server. An option command will
2179 move back to the connecting state (see nbd_aio_is_connecting(3)). Note
2180 that this state cannot be reached unless requested by
2181 nbd_set_opt_mode(3), and even then it only works with newstyle servers;
2182 an oldstyle server will skip straight to nbd_aio_is_ready(3).
2183 val aio_is_ready : t -> bool
2187 check if the connection is in the ready state
2189 Return true if this connection is connected to the NBD server, the
2191 handshake has completed, and the connection is idle or waiting for a
2192 reply. In this state the handle is ready to issue commands.
2193 val aio_is_processing : t -> bool
2197 check if the connection is processing a command
2199 Return true if this connection is connected to the NBD server, the
2201 handshake has completed, and the connection is processing commands (ei‐
2202 ther writing out a request or reading a reply).
2203 Note the ready state (nbd_aio_is_ready(3)) is not included. In the
2205 ready state commands may be *in flight* (the *server* is processing
2206 them), but libnbd is not processing them.
2207 val aio_is_dead : t -> bool
2211 check if the connection is dead
2213 Return true if the connection has encountered a fatal error and is
2215 dead. In this state the handle may only be closed. There is no way to
2216 recover a handle from the dead state.
2217 val aio_is_closed : t -> bool
2221 check if the connection is closed
2223 Return true if the connection has closed. There is no way to reconnect
2225 a closed connection. Instead you must close the whole handle.
2226 val aio_command_completed : t -> int64 -> bool
2230 check if the command completed
2232 Return true if the command completed. If this function returns true
2234 then the command was successful and it has been retired. Return false
2235 if the command is still in flight. This can also fail with an error in
2236 case the command failed (in this case the command is also retired). A
2237 command is retired either via this command, or by using a completion
2238 callback which returns 1.
2239 The "cookie" parameter is the positive unique 64 bit cookie for the
2241 command, as returned by a call such as nbd_aio_pread(3).
2242 val aio_peek_command_completed : t -> int64
2246 check if any command has completed
2248 Return the unique positive 64 bit cookie of the first non-retired but
2250 completed command, 0 if there are in-flight commands but none of them
2251 are awaiting retirement, or -1 on error including when there are no
2252 in-flight commands. Any cookie returned by this function must still be
2253 passed to nbd_aio_command_completed(3) to actually retire the command
2254 and learn whether the command was successful.
2255 val aio_in_flight : t -> int
2259 check how many aio commands are still in flight
2261 Return the number of in-flight aio commands that are still awaiting a
2263 response from the server before they can be retired. If this returns a
2264 non-zero value when requesting a disconnect from the server (see
2265 nbd_aio_disconnect(3) and nbd_shutdown(3)), libnbd does not try to wait
2266 for those commands to complete gracefully; if the server strands com‐
2267 mands while shutting down, nbd_aio_command_completed(3) will report
2268 those commands as failed with a status of "ENOTCONN".
2269 val connection_state : t -> string
2273 return string describing the state of the connection
2275 Returns a descriptive string for the state of the connection. This can
2277 be used for debugging or troubleshooting, but you should not rely on
2278 the state of connections since it may change in future versions.
2279 val get_package_name : t -> string
2283 return the name of the library
2285 Returns the name of the library, always "libnbd" unless the library was
2287 modified with another name at compile time.
2288 val get_version : t -> string
2292 return the version of the library
2294 Return the version of libnbd. This is returned as a string in the form
2296 "major.minor.release" where each of major, minor and release is a small
2297 positive integer. For example:
2298 minor ↓ "1.0.3" ↑ ↑ major release
2300 major = 0 The major number was 0 for the early experimental versions of
2302 libnbd where we still had an unstable API.
2303 major = 1 The major number is 1 for the versions of libnbd with a
2305 long-term stable API and ABI. It is not anticipated that major will be
2306 any number other than 1.
2307 minor = 0, 2, ... (even) The minor number is even for stable releases.
2309 minor = 1, 3, ... (odd) The minor number is odd for development ver‐
2311 sions. Note that new APIs added in a development version remain exper‐
2312 imental and subject to change in that branch until they appear in a
2313 stable release.
2314 release The release number is incremented for each release along a par‐
2316 ticular branch.
2317 val kill_subprocess : t -> int -> unit
2321 kill server running as a subprocess
2323 This call may be used to kill the server running as a subprocess that
2325 was previously created using nbd_connect_command(3). You do not need to
2326 use this call. It is only needed if the server does not exit when the
2327 socket is closed.
2328 The "signum" parameter is the optional signal number to send (see sig‐
2330 nal(7)). If "signum" is 0 then "SIGTERM" is sent.
2331 val supports_tls : t -> bool
2335 true if libnbd was compiled with support for TLS
2337 Returns true if libnbd was compiled with gnutls which is required to
2339 support TLS encryption, or false if not.
2340 val supports_uri : t -> bool
2344 true if libnbd was compiled with support for NBD URIs
2346 Returns true if libnbd was compiled with libxml2 which is required to
2348 support NBD URIs, or false if not.
2349 val get_uri : t -> string
2353 construct an NBD URI for a connection
2355 This makes a best effort attempt to construct an NBD URI which could be
2357 used to connect back to the same server (using nbd_connect_uri(3)).
2358 In some cases there is not enough information in the handle to success‐
2360 fully create a URI (eg. if you connected with nbd_connect_socket(3)).
2361 In such cases the call returns "NULL" and further diagnostic informa‐
2362 tion is available via nbd_get_errno(3) and nbd_get_error(3) as usual.
2363 Even if a URI is returned it is not guaranteed to work, and it may not
2365 be optimal.
2366OCamldoc 2021-10-25 NBD(3)