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 * Unix.error option
29 Exception thrown when an API call fails.
32 The string is the error message, and the int is the Unix.error (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 val errno_of_unix_error : Unix.error -> int
142 Return the raw C errno corresponding to a Unix.error . This can be
144 used in callbacks to update the int ref parameter.
145 type t
148 The handle.
151 val create : unit -> t
155 Create a new handle.
157 val close : t -> unit
161 Close a handle.
163 Handles can also be closed by the garbage collector when they become
165 unreachable. This call is used only if you want to force the handle to
166 close now and reclaim resources immediately.
167 val with_handle : (t -> 'a) -> 'a
171 Wrapper around NBD.create . It calls the function parameter with a
173 newly created handle, and ensures that NBD.close is always called even
174 if the function throws an exception.
175 Use this when it is essential that the handle is closed in order to
177 free up external resources in a timely manner; for example if running
178 the server as a subprocess and you want to ensure that the subprocess
179 is always killed; or if you need to disconnect from the server before
180 continuing with another operation.
181 val set_debug : t -> bool -> unit
185 NBD.set_debug t debug
188 set or clear the debug flag
190 Set or clear the debug flag. When debugging is enabled, debugging mes‐
192 sages from the library are printed to stderr, unless a debugging call‐
193 back has been defined too (see nbd_set_debug_callback(3)) in which case
194 they are sent to that function. This flag defaults to false on newly
195 created handles, except if "LIBNBD_DEBUG=1" is set in the environment
196 in which case it defaults to true.
197 val get_debug : t -> bool
201 NBD.get_debug t
204 return the state of the debug flag
206 Return the state of the debug flag on this handle.
208 val set_debug_callback : t -> (string -> string -> int) -> unit
212 NBD.set_debug_callback t debug
215 set the debug callback
217 Set the debug callback. This function is called when the library emits
219 debug messages, when debugging is enabled on a handle. The callback pa‐
220 rameters are "user_data" passed to this function, the name of the
221 libnbd function emitting the debug message ("context"), and the message
222 itself ("msg"). If no debug callback is set on a handle then messages
223 are printed on "stderr".
224 The callback should not call "nbd_*" APIs on the same handle since it
226 can be called while holding the handle lock and will cause a deadlock.
227 val clear_debug_callback : t -> unit
231 NBD.clear_debug_callback t
234 clear the debug callback
236 Remove the debug callback if one was previously associated with the
238 handle (with nbd_set_debug_callback(3)). If no callback was associated
239 this does nothing.
240 val set_handle_name : t -> string -> unit
244 NBD.set_handle_name t handle_name
247 set the handle name
249 Handles have a name which is unique within the current process. The
251 handle name is used in debug output.
252 Handle names are normally generated automatically and have the form
254 "nbd1", "nbd2", etc., but you can optionally use this call to give the
255 handles a name which is meaningful for your application to make debug‐
256 ging output easier to understand.
257 val get_handle_name : t -> string
261 NBD.get_handle_name t
264 get the handle name
266 Get the name of the handle. If it was previously set by calling
268 nbd_set_handle_name(3) then this returns the name that was set. Other‐
269 wise it will return a generic name like "nbd1", "nbd2", etc.
270 val set_private_data : t -> int -> int
274 NBD.set_private_data t private_data
277 set the per-handle private data
279 Handles contain a private data field for applications to use for any
281 purpose.
282 When calling libnbd from C, the type of this field is "uintptr_t" so it
284 can be used to store an unsigned integer or a pointer.
285 In non-C bindings it can be used to store an unsigned integer.
287 This function sets the value of this field and returns the old value
289 (or 0 if it was not previously set).
290 val get_private_data : t -> int
294 NBD.get_private_data t
297 get the per-handle private data
299 Return the value of the private data field set previously by a call to
301 nbd_set_private_data(3) (or 0 if it was not previously set).
302 val set_export_name : t -> string -> unit
306 NBD.set_export_name t export_name
309 set the export name
311 For servers which require an export name or can serve different content
313 on different exports, set the "export_name" to connect to. The default
314 is the empty string "".
315 This is only relevant when connecting to servers using the newstyle
317 protocol as the oldstyle protocol did not support export names. The NBD
318 protocol limits export names to 4096 bytes, but servers may not support
319 the full length. The encoding of export names is always UTF-8.
320 When option mode is not in use, the export name must be set before be‐
322 ginning a connection. However, when nbd_set_opt_mode(3) has enabled op‐
323 tion mode, it is possible to change the export name prior to
324 nbd_opt_go(3). In particular, the use of nbd_opt_list(3) during negoti‐
325 ation can be used to determine a name the server is likely to accept,
326 and nbd_opt_info(3) can be used to learn details about an export before
327 connecting.
328 This call may be skipped if using nbd_connect_uri(3) to connect to a
330 URI that includes an export name.
331 val get_export_name : t -> string
335 NBD.get_export_name t
338 get the export name
340 Get the export name associated with the handle. This is the name that
342 libnbd requests; see nbd_get_canonical_export_name(3) for determining
343 if the server has a different canonical name for the given export (most
344 common when requesting the default export name of an empty string "")
345 val set_request_block_size : t -> bool -> unit
349 NBD.set_request_block_size t request
352 control whether NBD_OPT_GO requests block size
354 By default, when connecting to an export, libnbd requests that the
356 server report any block size restrictions. The NBD protocol states that
357 a server may supply block sizes regardless of whether the client re‐
358 quests them, and libnbd will report those block sizes (see
359 nbd_get_block_size(3)); conversely, if a client does not request block
360 sizes, the server may reject the connection instead of dealing with a
361 client sending unaligned requests. This function makes it possible to
362 test server behavior by emulating older clients.
363 Note that even when block size is requested, the server is not obli‐
365 gated to provide any. Furthermore, if block sizes are provided (whether
366 or not the client requested them), libnbd enforces alignment to those
367 sizes unless nbd_set_strict_mode(3) is used to bypass client-side
368 safety checks.
369 val get_request_block_size : t -> bool
373 NBD.get_request_block_size t
376 see if NBD_OPT_GO requests block size
378 Return the state of the block size request flag on this handle.
380 val set_full_info : t -> bool -> unit
384 NBD.set_full_info t request
387 control whether NBD_OPT_GO requests extra details
389 By default, when connecting to an export, libnbd only requests the de‐
391 tails it needs to service data operations. The NBD protocol says that a
392 server can supply optional information, such as a canonical name of the
393 export (see nbd_get_canonical_export_name(3)) or a description of the
394 export (see nbd_get_export_description(3)), but that a hint from the
395 client makes it more likely for this extra information to be provided.
396 This function controls whether libnbd will provide that hint.
397 Note that even when full info is requested, the server is not obligated
399 to reply with all information that libnbd requested. Similarly, libnbd
400 will ignore any optional server information that libnbd has not yet
401 been taught to recognize. Furthermore, the hint to request block sizes
402 is independently controlled via nbd_set_request_block_size(3).
403 val get_full_info : t -> bool
407 NBD.get_full_info t
410 see if NBD_OPT_GO requests extra details
412 Return the state of the full info request flag on this handle.
414 val get_canonical_export_name : t -> string
418 NBD.get_canonical_export_name t
421 return the canonical export name, if the server has one
423 The NBD protocol permits a server to report an optional canonical ex‐
425 port name, which may differ from the client's request (as set by
426 nbd_set_export_name(3) or nbd_connect_uri(3)). This function accesses
427 any name returned by the server; it may be the same as the client re‐
428 quest, but is more likely to differ when the client requested a connec‐
429 tion to the default export name (an empty string "").
430 Some servers are unlikely to report a canonical name unless the client
432 specifically hinted about wanting it, via nbd_set_full_info(3).
433 val get_export_description : t -> string
437 NBD.get_export_description t
440 return the export description, if the server has one
442 The NBD protocol permits a server to report an optional export descrip‐
444 tion. This function reports any description returned by the server.
445 Some servers are unlikely to report a description unless the client
447 specifically hinted about wanting it, via nbd_set_full_info(3). For
448 qemu-nbd(8), a description is set with *-D*.
449 val set_tls : t -> TLS.t -> unit
453 NBD.set_tls t tls
456 enable or require TLS (authentication and encryption)
458 Enable or require TLS (authenticated and encrypted connections) to the
460 NBD server. The possible settings are:
461 "LIBNBD_TLS_DISABLE" Disable TLS. (The default setting, unless using
463 nbd_connect_uri(3) with a URI that requires TLS)
464 "LIBNBD_TLS_ALLOW" Enable TLS if possible.
466 This option is insecure (or best effort) in that in some cases it will
468 fall back to an unencrypted and/or unauthenticated connection if TLS
469 could not be established. Use "LIBNBD_TLS_REQUIRE" below if the connec‐
470 tion must be encrypted.
471 Some servers will drop the connection if TLS fails so fallback may not
473 be possible.
474 "LIBNBD_TLS_REQUIRE" Require an encrypted and authenticated TLS connec‐
476 tion. Always fail to connect if the connection is not encrypted and au‐
477 thenticated.
478 As well as calling this you may also need to supply the path to the
480 certificates directory (nbd_set_tls_certificates(3)), the username
481 (nbd_set_tls_username(3)) and/or the Pre-Shared Keys (PSK) file
482 (nbd_set_tls_psk_file(3)). For now, when using nbd_connect_uri(3), any
483 URI query parameters related to TLS are not handled automatically. Set‐
484 ting the level higher than zero will fail if libnbd was not compiled
485 against gnutls; you can test whether this is the case with nbd_sup‐
486 ports_tls(3).
487 val get_tls : t -> TLS.t
491 NBD.get_tls t
494 get the TLS request setting
496 Get the TLS request setting.
498 Note: If you want to find out if TLS was actually negotiated on a par‐
500 ticular connection use nbd_get_tls_negotiated(3) instead.
501 val get_tls_negotiated : t -> bool
505 NBD.get_tls_negotiated t
508 find out if TLS was negotiated on a connection
510 After connecting you may call this to find out if the connection is us‐
512 ing TLS.
513 This is only really useful if you set the TLS request mode to
515 "LIBNBD_TLS_ALLOW" (see nbd_set_tls(3)), because in this mode we try to
516 use TLS but fall back to unencrypted if it was not available. This
517 function will tell you if TLS was negotiated or not.
518 In "LIBNBD_TLS_REQUIRE" mode (the most secure) the connection would
520 have failed if TLS could not be negotiated, and in "LIBNBD_TLS_DISABLE"
521 mode TLS is not tried.
522 val set_tls_certificates : t -> string -> unit
526 NBD.set_tls_certificates t dir
529 set the path to the TLS certificates directory
531 Set the path to the TLS certificates directory. If not set and TLS is
533 used then a compiled in default is used. For root this is
534 "/etc/pki/libnbd/". For non-root this is "$HOME/.pki/libnbd" and
535 "$HOME/.config/pki/libnbd". If none of these directories can be found
536 then the system trusted CAs are used.
537 This function may be called regardless of whether TLS is supported, but
539 will have no effect unless nbd_set_tls(3) is also used to request or
540 require TLS.
541 val set_tls_verify_peer : t -> bool -> unit
545 NBD.set_tls_verify_peer t verify
548 set whether we verify the identity of the server
550 Set this flag to control whether libnbd will verify the identity of the
552 server from the server's certificate and the certificate authority.
553 This defaults to true when connecting to TCP servers using TLS certifi‐
554 cate authentication, and false otherwise.
555 This function may be called regardless of whether TLS is supported, but
557 will have no effect unless nbd_set_tls(3) is also used to request or
558 require TLS.
559 val get_tls_verify_peer : t -> bool
563 NBD.get_tls_verify_peer t
566 get whether we verify the identity of the server
568 Get the verify peer flag.
570 val set_tls_username : t -> string -> unit
574 NBD.set_tls_username t username
577 set the TLS username
579 Set the TLS client username. This is used if authenticating with PSK
581 over TLS is enabled. If not set then the local username is used.
582 This function may be called regardless of whether TLS is supported, but
584 will have no effect unless nbd_set_tls(3) is also used to request or
585 require TLS.
586 val get_tls_username : t -> string
590 NBD.get_tls_username t
593 get the current TLS username
595 Get the current TLS username.
597 val set_tls_psk_file : t -> string -> unit
601 NBD.set_tls_psk_file t filename
604 set the TLS Pre-Shared Keys (PSK) filename
606 Set the TLS Pre-Shared Keys (PSK) filename. This is used if trying to
608 authenticate to the server using with a pre-shared key. There is no de‐
609 fault so if this is not set then PSK authentication cannot be used to
610 connect to the server.
611 This function may be called regardless of whether TLS is supported, but
613 will have no effect unless nbd_set_tls(3) is also used to request or
614 require TLS.
615 val set_request_structured_replies : t -> bool -> unit
619 NBD.set_request_structured_replies t request
622 control use of structured replies
624 By default, libnbd tries to negotiate structured replies with the
626 server, as this protocol extension must be in use before
627 nbd_can_meta_context(3) or nbd_can_df(3) can return true. However, for
628 integration testing, it can be useful to clear this flag rather than
629 find a way to alter the server to fail the negotiation request.
630 val get_request_structured_replies : t -> bool
634 NBD.get_request_structured_replies t
637 see if structured replies are attempted
639 Return the state of the request structured replies flag on this handle.
641 Note: If you want to find out if structured replies were actually nego‐
643 tiated on a particular connection use nbd_get_structured_replies_nego‐
644 tiated(3) instead.
645 val get_structured_replies_negotiated : t -> bool
649 NBD.get_structured_replies_negotiated t
652 see if structured replies are in use
654 After connecting you may call this to find out if the connection is us‐
656 ing structured replies.
657 val set_handshake_flags : t -> HANDSHAKE_FLAG.t list -> unit
661 NBD.set_handshake_flags t flags
664 control use of handshake flags
666 By default, libnbd tries to negotiate all possible handshake flags that
668 are also supported by the server, since omitting a handshake flag can
669 prevent the use of other functionality such as TLS encryption or struc‐
670 tured replies. However, for integration testing, it can be useful to
671 reduce the set of flags supported by the client to test that a particu‐
672 lar server can handle various clients that were compliant to older ver‐
673 sions of the NBD specification.
674 The "flags" argument is a bitmask, including zero or more of the fol‐
676 lowing handshake flags:
677 "LIBNBD_HANDSHAKE_FLAG_FIXED_NEWSTYLE" = 1 The server gracefully han‐
679 dles unknown option requests from the client, rather than disconnect‐
680 ing. Without this flag, a client cannot safely request to use exten‐
681 sions such as TLS encryption or structured replies, as the request may
682 cause an older server to drop the connection.
683 "LIBNBD_HANDSHAKE_FLAG_NO_ZEROES" = 2 If the client is forced to use
685 "NBD_OPT_EXPORT_NAME" instead of the preferred "NBD_OPT_GO", this flag
686 allows the server to send fewer all-zero padding bytes over the connec‐
687 tion.
688 For convenience, the constant "LIBNBD_HANDSHAKE_FLAG_MASK" is available
690 to describe all flags supported by this build of libnbd. Future NBD ex‐
691 tensions may add further flags, which in turn may be enabled by default
692 in newer libnbd. As such, when attempting to disable only one specific
693 bit, it is wiser to first call nbd_get_handshake_flags(3) and modify
694 that value, rather than blindly setting a constant value.
695 val get_handshake_flags : t -> HANDSHAKE_FLAG.t list
699 NBD.get_handshake_flags t
702 see which handshake flags are supported
704 Return the state of the handshake flags on this handle. When the han‐
706 dle has not yet completed a connection (see nbd_aio_is_created(3)),
707 this returns the flags that the client is willing to use, provided the
708 server also advertises those flags. After the connection is ready (see
709 nbd_aio_is_ready(3)), this returns the flags that were actually agreed
710 on between the server and client. If the NBD protocol defines new
711 handshake flags, then the return value from a newer library version may
712 include bits that were undefined at the time of compilation.
713 val set_pread_initialize : t -> bool -> unit
717 NBD.set_pread_initialize t request
720 control whether libnbd pre-initializes read buffers
722 By default, libnbd will pre-initialize the contents of a buffer passed
724 to calls such as nbd_pread(3) to all zeroes prior to checking for any
725 other errors, so that even if a client application passed in an unini‐
726 tialized buffer but fails to check for errors, it will not result in a
727 potential security risk caused by an accidental leak of prior heap con‐
728 tents (see CVE-2022-0485 in libnbd-security(3) for an example of a se‐
729 curity hole in an application built against an earlier version of
730 libnbd that lacked consistent pre-initialization). However, for a
731 client application that has audited that an uninitialized buffer is
732 never dereferenced, or which performs its own pre-initialization,
733 libnbd's sanitization efforts merely pessimize performance (although
734 the time spent in pre-initialization may pale in comparison to time
735 spent waiting on network packets).
736 Calling this function with "request" set to false tells libnbd to skip
738 the buffer initialization step in read commands.
739 val get_pread_initialize : t -> bool
743 NBD.get_pread_initialize t
746 see whether libnbd pre-initializes read buffers
748 Return whether libnbd performs a pre-initialization of a buffer passed
750 to nbd_pread(3) and similar to all zeroes, as set by nbd_set_pread_ini‐
751 tialize(3).
752 val set_strict_mode : t -> STRICT.t list -> unit
756 NBD.set_strict_mode t flags
759 control how strictly to follow NBD protocol
761 By default, libnbd tries to detect requests that would trigger unde‐
763 fined behavior in the NBD protocol, and rejects them client side with‐
764 out causing any network traffic, rather than risking undefined server
765 behavior. However, for integration testing, it can be handy to relax
766 the strictness of libnbd, to coerce it into sending such requests over
767 the network for testing the robustness of the server in dealing with
768 such traffic.
769 The "flags" argument is a bitmask, including zero or more of the fol‐
771 lowing strictness flags:
772 "LIBNBD_STRICT_COMMANDS" = 0x1 If set, this flag rejects client re‐
774 quests that do not comply with the set of advertised server flags (for
775 example, attempting a write on a read-only server, or attempting to use
776 "LIBNBD_CMD_FLAG_FUA" when nbd_can_fua(3) returned false). If clear,
777 this flag relies on the server to reject unexpected commands.
778 "LIBNBD_STRICT_FLAGS" = 0x2 If set, this flag rejects client requests
780 that attempt to set a command flag not recognized by libnbd (those out‐
781 side of "LIBNBD_CMD_FLAG_MASK"), or a flag not normally associated with
782 a command (such as using "LIBNBD_CMD_FLAG_FUA" on a read command). If
783 clear, all flags are sent on to the server, even if sending such a flag
784 may cause the server to change its reply in a manner that confuses
785 libnbd, perhaps causing deadlock or ending the connection.
786 Flags that are known by libnbd as associated with a given command (such
788 as "LIBNBD_CMD_FLAG_DF" for nbd_pread_structured(3) gated by
789 nbd_can_df(3)) are controlled by "LIBNBD_STRICT_COMMANDS" instead.
790 Note that the NBD protocol only supports 16 bits of command flags, even
792 though the libnbd API uses "uint32_t"; bits outside of the range per‐
793 mitted by the protocol are always a client-side error.
794 "LIBNBD_STRICT_BOUNDS" = 0x4 If set, this flag rejects client requests
796 that would exceed the export bounds without sending any traffic to the
797 server. If clear, this flag relies on the server to detect
798 out-of-bounds requests.
799 "LIBNBD_STRICT_ZERO_SIZE" = 0x8 If set, this flag rejects client re‐
801 quests with length 0. If clear, this permits zero-length requests to
802 the server, which may produce undefined results.
803 "LIBNBD_STRICT_ALIGN" = 0x10 If set, and the server provided minimum
805 block sizes (see nbd_get_block_size(3), this flag rejects client re‐
806 quests that do not have length and offset aligned to the server's mini‐
807 mum requirements. If clear, unaligned requests are sent to the server,
808 where it is up to the server whether to honor or reject the request.
809 For convenience, the constant "LIBNBD_STRICT_MASK" is available to de‐
811 scribe all strictness flags supported by this build of libnbd. Future
812 versions of libnbd may add further flags, which are likely to be en‐
813 abled by default for additional client-side filtering. As such, when
814 attempting to relax only one specific bit while keeping remaining
815 checks at the client side, it is wiser to first call
816 nbd_get_strict_mode(3) and modify that value, rather than blindly set‐
817 ting a constant value.
818 val get_strict_mode : t -> STRICT.t list
822 NBD.get_strict_mode t
825 see which strictness flags are in effect
827 Return flags indicating which protocol strictness items are being en‐
829 forced locally by libnbd rather than the server. The return value from
830 a newer library version may include bits that were undefined at the
831 time of compilation.
832 val set_opt_mode : t -> bool -> unit
836 NBD.set_opt_mode t enable
839 control option mode, for pausing during option negotiation
841 Set this flag to true in order to request that a connection command
843 "nbd_connect_*" will pause for negotiation options rather than proceed‐
844 ing all the way to the ready state, when communicating with a newstyle
845 server. This setting has no effect when connecting to an oldstyle
846 server.
847 When option mode is enabled, you have fine-grained control over which
849 options are negotiated, compared to the default of the server negotiat‐
850 ing everything on your behalf using settings made before starting the
851 connection. To leave the mode and proceed on to the ready state, you
852 must use nbd_opt_go(3) successfully; a failed nbd_opt_go(3) returns to
853 the negotiating state to allow a change of export name before trying
854 again. You may also use nbd_opt_abort(3) to end the connection without
855 finishing negotiation.
856 val get_opt_mode : t -> bool
860 NBD.get_opt_mode t
863 return whether option mode was enabled
865 Return true if option negotiation mode was enabled on this handle.
867 val opt_go : t -> unit
871 NBD.opt_go t
874 end negotiation and move on to using an export
876 Request that the server finish negotiation and move on to serving the
878 export previously specified by the most recent nbd_set_export_name(3)
879 or nbd_connect_uri(3). This can only be used if nbd_set_opt_mode(3)
880 enabled option mode.
881 If this fails, the server may still be in negotiation, where it is pos‐
883 sible to attempt another option such as a different export name; al‐
884 though older servers will instead have killed the connection.
885 val opt_abort : t -> unit
889 NBD.opt_abort t
892 end negotiation and close the connection
894 Request that the server finish negotiation, gracefully if possible,
896 then close the connection. This can only be used if nbd_set_opt_mode(3)
897 enabled option mode.
898 val opt_list : t -> (string -> string -> int) -> int
902 NBD.opt_list t list
905 request the server to list all exports during negotiation
907 Request that the server list all exports that it supports. This can
909 only be used if nbd_set_opt_mode(3) enabled option mode.
910 The "list" function is called once per advertised export, with any
912 "user_data" passed to this function, and with "name" and "description"
913 supplied by the server. Many servers omit descriptions, in which case
914 "description" will be an empty string. Remember that it is not safe to
915 call nbd_set_export_name(3) from within the context of the callback
916 function; rather, your code must copy any "name" needed for later use
917 after this function completes. At present, the return value of the
918 callback is ignored, although a return of -1 should be avoided.
919 For convenience, when this function succeeds, it returns the number of
921 exports that were advertised by the server.
922 Not all servers understand this request, and even when it is under‐
924 stood, the server might intentionally send an empty list to avoid being
925 an information leak, may encounter a failure after delivering partial
926 results, or may refuse to answer more than one query per connection in
927 the interest of avoiding negotiation that does not resolve. Thus, this
928 function may succeed even when no exports are reported, or may fail but
929 have a non-empty list. Likewise, the NBD protocol does not specify an
930 upper bound for the number of exports that might be advertised, so
931 client code should be aware that a server may send a lengthy list.
932 For nbd-server(1) you will need to allow clients to make list requests
934 by adding "allowlist=true" to the " generic " section of
935 /etc/nbd-server/config. For qemu-nbd(8), a description is set with
936 *-D*.
937 val opt_info : t -> unit
941 NBD.opt_info t
944 request the server for information about an export
946 Request that the server supply information about the export name previ‐
948 ously specified by the most recent nbd_set_export_name(3) or nbd_con‐
949 nect_uri(3). This can only be used if nbd_set_opt_mode(3) enabled op‐
950 tion mode.
951 If successful, functions like nbd_is_read_only(3) and nbd_get_size(3)
953 will report details about that export. In general, if nbd_opt_go(3) is
954 called next, that call will likely succeed with the details remaining
955 the same, although this is not guaranteed by all servers.
956 Not all servers understand this request, and even when it is under‐
958 stood, the server might fail the request even when a corresponding
959 nbd_opt_go(3) would succeed.
960 val opt_list_meta_context : t -> (string -> int) -> int
964 NBD.opt_list_meta_context t context
967 request the server to list available meta contexts
969 Request that the server list available meta contexts associated with
971 the export previously specified by the most recent nbd_set_ex‐
972 port_name(3) or nbd_connect_uri(3). This can only be used if
973 nbd_set_opt_mode(3) enabled option mode.
974 The NBD protocol allows a client to decide how many queries to ask the
976 server. Rather than taking that list of queries as a parameter to this
977 function, libnbd reuses the current list of requested meta contexts as
978 set by nbd_add_meta_context(3); you can use nbd_clear_meta_contexts(3)
979 to set up a different list of queries. When the list is empty, a server
980 will typically reply with all contexts that it supports; when the list
981 is non-empty, the server will reply only with supported contexts that
982 match the client's request. Note that a reply by the server might be
983 encoded to represent several feasible contexts within one string,
984 rather than multiple strings per actual context name that would actu‐
985 ally succeed during nbd_opt_go(3); so it is still necessary to use
986 nbd_can_meta_context(3) after connecting to see which contexts are ac‐
987 tually supported.
988 The "context" function is called once per server reply, with any
990 "user_data" passed to this function, and with "name" supplied by the
991 server. Remember that it is not safe to call nbd_add_meta_context(3)
992 from within the context of the callback function; rather, your code
993 must copy any "name" needed for later use after this function com‐
994 pletes. At present, the return value of the callback is ignored, al‐
995 though a return of -1 should be avoided.
996 For convenience, when this function succeeds, it returns the number of
998 replies returned by the server.
999 Not all servers understand this request, and even when it is under‐
1001 stood, the server might intentionally send an empty list because it
1002 does not support the requested context, or may encounter a failure af‐
1003 ter delivering partial results. Thus, this function may succeed even
1004 when no contexts are reported, or may fail but have a non-empty list.
1005 Likewise, the NBD protocol does not specify an upper bound for the num‐
1006 ber of replies that might be advertised, so client code should be aware
1007 that a server may send a lengthy list.
1008 val add_meta_context : t -> string -> unit
1012 NBD.add_meta_context t name
1015 ask server to negotiate metadata context
1017 During connection libnbd can negotiate zero or more metadata contexts
1019 with the server. Metadata contexts are features (such as "base:alloca‐
1020 tion") which describe information returned by the nbd_block_status(3)
1021 command (for "base:allocation" this is whether blocks of data are allo‐
1022 cated, zero or sparse).
1023 This call adds one metadata context to the list to be negotiated. You
1025 can call it as many times as needed. The list is initially empty when
1026 the handle is created; you can check the contents of the list with
1027 nbd_get_nr_meta_contexts(3) and nbd_get_meta_context(3), or clear it
1028 with nbd_clear_meta_contexts(3).
1029 The NBD protocol limits meta context names to 4096 bytes, but servers
1031 may not support the full length. The encoding of meta context names is
1032 always UTF-8.
1033 Not all servers support all metadata contexts. To learn if a context
1035 was actually negotiated, call nbd_can_meta_context(3) after connecting.
1036 The single parameter is the name of the metadata context, for example
1038 "LIBNBD_CONTEXT_BASE_ALLOCATION". <libnbd.h> includes defined con‐
1039 stants beginning with "LIBNBD_CONTEXT_" for some well-known contexts,
1040 but you are free to pass in other contexts.
1041 Other metadata contexts are server-specific, but include
1043 "qemu:dirty-bitmap:..." and "qemu:allocation-depth" for qemu-nbd (see
1044 qemu-nbd *-B* and *-A* options).
1045 val get_nr_meta_contexts : t -> int
1049 NBD.get_nr_meta_contexts t
1052 return the current number of requested meta contexts
1054 During connection libnbd can negotiate zero or more metadata contexts
1056 with the server. Metadata contexts are features (such as "base:alloca‐
1057 tion") which describe information returned by the nbd_block_status(3)
1058 command (for "base:allocation" this is whether blocks of data are allo‐
1059 cated, zero or sparse).
1060 This command returns how many meta contexts have been added to the list
1062 to request from the server via nbd_add_meta_context(3). The server is
1063 not obligated to honor all of the requests; to see what it actually
1064 supports, see nbd_can_meta_context(3).
1065 val get_meta_context : t -> int -> string
1069 NBD.get_meta_context t i
1072 return the i'th meta context request
1074 During connection libnbd can negotiate zero or more metadata contexts
1076 with the server. Metadata contexts are features (such as "base:alloca‐
1077 tion") which describe information returned by the nbd_block_status(3)
1078 command (for "base:allocation" this is whether blocks of data are allo‐
1079 cated, zero or sparse).
1080 This command returns the i'th meta context request, as added by
1082 nbd_add_meta_context(3), and bounded by nbd_get_nr_meta_contexts(3).
1083 val clear_meta_contexts : t -> unit
1087 NBD.clear_meta_contexts t
1090 reset the list of requested meta contexts
1092 During connection libnbd can negotiate zero or more metadata contexts
1094 with the server. Metadata contexts are features (such as "base:alloca‐
1095 tion") which describe information returned by the nbd_block_status(3)
1096 command (for "base:allocation" this is whether blocks of data are allo‐
1097 cated, zero or sparse).
1098 This command resets the list of meta contexts to request back to an
1100 empty list, for re-population by further use of nbd_add_meta_con‐
1101 text(3). It is primarily useful when option negotiation mode is se‐
1102 lected (see nbd_set_opt_mode(3)), for altering the list of attempted
1103 contexts between subsequent export queries.
1104 val set_uri_allow_transports : t -> ALLOW_TRANSPORT.t list -> unit
1108 NBD.set_uri_allow_transports t mask
1111 set the allowed transports in NBD URIs
1113 Set which transports are allowed to appear in NBD URIs. The default is
1115 to allow any transport.
1116 The "mask" parameter may contain any of the following flags ORed to‐
1118 gether:
1119 "LIBNBD_ALLOW_TRANSPORT_TCP" = 0x1 "LIBNBD_ALLOW_TRANSPORT_UNIX" = 0x2
1121 "LIBNBD_ALLOW_TRANSPORT_VSOCK" = 0x4
1122 For convenience, the constant "LIBNBD_ALLOW_TRANSPORT_MASK" is avail‐
1124 able to describe all transports recognized by this build of libnbd. A
1125 future version of the library may add new flags.
1126 val set_uri_allow_tls : t -> TLS.t -> unit
1130 NBD.set_uri_allow_tls t tls
1133 set the allowed TLS settings in NBD URIs
1135 Set which TLS settings are allowed to appear in NBD URIs. The default
1137 is to allow either non-TLS or TLS URIs.
1138 The "tls" parameter can be:
1140 "LIBNBD_TLS_DISABLE" TLS URIs are not permitted, ie. a URI such as
1142 "nbds://..." will be rejected.
1143 "LIBNBD_TLS_ALLOW" This is the default. TLS may be used or not, depend‐
1145 ing on whether the URI uses "nbds" or "nbd".
1146 "LIBNBD_TLS_REQUIRE" TLS URIs are required. All URIs must use "nbds".
1148 val set_uri_allow_local_file : t -> bool -> unit
1152 NBD.set_uri_allow_local_file t allow
1155 set the allowed transports in NBD URIs
1157 Allow NBD URIs to reference local files. This is *disabled* by default.
1159 Currently this setting only controls whether the "tls-psk-file" parame‐
1161 ter in NBD URIs is allowed.
1162 val connect_uri : t -> string -> unit
1166 NBD.connect_uri t uri
1169 connect to NBD URI
1171 Connect (synchronously) to an NBD server and export by specifying the
1173 NBD URI. This call parses the URI and calls nbd_set_export_name(3) and
1174 nbd_set_tls(3) and other calls as needed, followed by nbd_con‐
1175 nect_tcp(3) or nbd_connect_unix(3).
1176 This call returns when the connection has been made.
1178 Example URIs supported "nbd://example.com" Connect over TCP, unen‐
1180 crypted, to "example.com" port 10809.
1181 "nbds://example.com" Connect over TCP with TLS, to "example.com" port
1183 10809. If the server does not support TLS then this will fail.
1184 "nbd+unix:///foo?socket=/tmp/nbd.sock" Connect over the Unix domain
1186 socket /tmp/nbd.sock to an NBD server running locally. The export name
1187 is set to "foo" (note without any leading "/" character).
1188 "nbds+unix://alice@/?socket=/tmp/nbd.sock&tls-certificat es=certs" Con‐
1190 nect over a Unix domain socket, enabling TLS and setting the path to a
1191 directory containing certificates and keys.
1192 "nbd+vsock:///" In this scenario libnbd is running in a virtual ma‐
1194 chine. Connect over "AF_VSOCK" to an NBD server running on the hypervi‐
1195 sor.
1196 Supported URI formats The following schemes are supported in the cur‐
1198 rent version of libnbd:
1199 "nbd:" Connect over TCP without using TLS.
1201 "nbds:" Connect over TCP. TLS is required and the connection will fail
1203 if the server does not support TLS.
1204 "nbd+unix:" "nbds+unix:" Connect over a Unix domain socket, without or
1206 with TLS respectively. The "socket" parameter is required.
1207 "nbd+vsock:" "nbds+vsock:" Connect over the "AF_VSOCK" transport, with‐
1209 out or with TLS respectively.
1210 The authority part of the URI (" username@ servername :port ") is
1212 parsed depending on the transport. For TCP it specifies the server to
1213 connect to and optional port number. For "+unix" it should not be
1214 present. For "+vsock" the server name is the numeric CID (eg. 2 to con‐
1215 nect to the host), and the optional port number may be present. If the
1216 "username" is present it is used for TLS authentication.
1217 For all transports, an export name may be present, parsed in accordance
1219 with the NBD URI specification.
1220 Finally the query part of the URI can contain:
1222 socket=SOCKET Specifies the Unix domain socket to connect on. Must be
1224 present for the "+unix" transport and must not be present for the other
1225 transports.
1226 tls-certificates=DIR Set the certificates directory. See
1228 nbd_set_tls_certificates(3). Note this is not allowed by default - see
1229 next section.
1230 tls-psk-file=PSKFILE Set the PSK file. See nbd_set_tls_psk_file(3).
1232 Note this is not allowed by default - see next section.
1233 Disable URI features For security reasons you might want to disable
1235 certain URI features. Pre-filtering URIs is error-prone and should not
1236 be attempted. Instead use the libnbd APIs below to control what can ap‐
1237 pear in URIs. Note you must call these functions on the same handle be‐
1238 fore calling nbd_connect_uri(3) or nbd_aio_connect_uri(3).
1239 TCP, Unix domain socket or "AF_VSOCK" transports Default: all allowed
1241 To select which transports are allowed call nbd_set_uri_allow_trans‐
1243 ports(3).
1244 TLS Default: both non-TLS and TLS connections allowed
1246 To force TLS off or on in URIs call nbd_set_uri_allow_tls(3).
1248 Connect to Unix domain socket in the local filesystem Default: allowed
1250 To prevent this you must disable the "+unix" transport using
1252 nbd_set_uri_allow_transports(3).
1253 Read from local files Default: denied
1255 To allow URIs to contain references to local files (eg. for parameters
1257 like "tls-psk-file") call nbd_set_uri_allow_local_file(3).
1258 Overriding the export name It is possible to override the export name
1260 portion of a URI by using nbd_set_opt_mode(3) to enable option mode,
1261 then using nbd_set_export_name(3) and nbd_opt_go(3) as part of subse‐
1262 quent negotiation.
1263 Optional features This call will fail if libnbd was not compiled with
1265 libxml2; you can test whether this is the case with nbd_sup‐
1266 ports_uri(3).
1267 Support for URIs that require TLS will fail if libnbd was not compiled
1269 with gnutls; you can test whether this is the case with nbd_sup‐
1270 ports_tls(3).
1271 Constructing a URI from an existing connection See nbd_get_uri(3).
1273 val connect_unix : t -> string -> unit
1277 NBD.connect_unix t unixsocket
1280 connect to NBD server over a Unix domain socket
1282 Connect (synchronously) over the named Unix domain socket ("unix‐
1284 socket") to an NBD server running on the same machine. This call re‐
1285 turns when the connection has been made.
1286 val connect_vsock : t -> int64 -> int64 -> unit
1290 NBD.connect_vsock t cid port
1293 connect to NBD server over AF_VSOCK protocol
1295 Connect (synchronously) over the "AF_VSOCK" protocol from a virtual ma‐
1297 chine to an NBD server, usually running on the host. The "cid" and
1298 "port" parameters specify the server address. Usually "cid" should be 2
1299 (to connect to the host), and "port" might be 10809 or another port
1300 number assigned to you by the host administrator. This call returns
1301 when the connection has been made.
1302 val connect_tcp : t -> string -> string -> unit
1306 NBD.connect_tcp t hostname port
1309 connect to NBD server over a TCP port
1311 Connect (synchronously) to the NBD server listening on "hostname:port".
1313 The "port" may be a port name such as "nbd", or it may be a port number
1314 as a string such as "10809". This call returns when the connection has
1315 been made.
1316 val connect_socket : t -> Unix.file_descr -> unit
1320 NBD.connect_socket t sock
1323 connect directly to a connected socket
1325 Pass a connected socket "sock" through which libnbd will talk to the
1327 NBD server.
1328 The caller is responsible for creating and connecting this socket by
1330 some method, before passing it to libnbd.
1331 If this call returns without error then socket ownership is passed to
1333 libnbd. Libnbd will close the socket when the handle is closed. The
1334 caller must not use the socket in any way.
1335 val connect_command : t -> string list -> unit
1339 NBD.connect_command t argv
1342 connect to NBD server command
1344 Run the command as a subprocess and connect to it over stdin/stdout.
1346 This is for use with NBD servers which can behave like inetd clients,
1347 such as nbdkit(1) using the *-s*/*--single* flag, and nbd-server(1)
1348 with port number set to 0.
1349 To run qemu-nbd(1), use nbd_connect_systemd_socket_activation(3) in‐
1351 stead.
1352 Subprocess Libnbd will fork the "argv" command and pass the NBD socket
1354 to it using file descriptors 0 and 1 (stdin/stdout):
1355 ┌─────────┬─────────┐ ┌────────────────┐ │ program │ libnbd │ │
1357 NBD server │ │ │ │ │ (argv) │ │ │
1358 socket ╍╍╍╍╍╍╍╍▶ stdin/stdout │ └─────────┴─────────┘
1359 └────────────────┘
1360 When the NBD handle is closed the server subprocess is killed.
1362 val connect_systemd_socket_activation : t -> string list -> unit
1366 NBD.connect_systemd_socket_activation t argv
1369 connect using systemd socket activation
1371 Run the command as a subprocess and connect to it using systemd socket
1373 activation.
1374 This is especially useful for running qemu-nbd(1) as a subprocess of
1376 libnbd, for example to use it to open qcow2 files.
1377 To run nbdkit as a subprocess, this function can be used, or nbd_con‐
1379 nect_command(3).
1380 To run nbd-server(1) as a subprocess, this function cannot be used, you
1382 must use nbd_connect_command(3).
1383 Socket activation Libnbd will fork the "argv" command and pass an NBD
1385 socket to it using special "LISTEN_*" environment variables (as defined
1386 by the systemd socket activation protocol).
1387 ┌─────────┬─────────┐ ┌───────────────┐ │ program │ libnbd │ │
1389 qemu-nbd or │ │ │ │ │ other server │ │ │
1390 socket ╍╍╍╍╍╍╍╍▶ │ └─────────┴─────────┘
1391 └───────────────┘
1392 When the NBD handle is closed the server subprocess is killed.
1394 val is_read_only : t -> bool
1398 NBD.is_read_only t
1401 is the NBD export read-only?
1403 Returns true if the NBD export is read-only; writes and write-like op‐
1405 erations will fail.
1406 This call does not block, because it returns data that is saved in the
1408 handle from the NBD protocol handshake.
1409 val can_flush : t -> bool
1413 NBD.can_flush t
1416 does the server support the flush command?
1418 Returns true if the server supports the flush command (see
1420 nbd_flush(3), nbd_aio_flush(3)). Returns false if the server does not.
1421 This call does not block, because it returns data that is saved in the
1423 handle from the NBD protocol handshake.
1424 val can_fua : t -> bool
1428 NBD.can_fua t
1431 does the server support the FUA flag?
1433 Returns true if the server supports the FUA flag on certain commands
1435 (see nbd_pwrite(3)).
1436 This call does not block, because it returns data that is saved in the
1438 handle from the NBD protocol handshake.
1439 val is_rotational : t -> bool
1443 NBD.is_rotational t
1446 is the NBD disk rotational (like a disk)?
1448 Returns true if the disk exposed over NBD is rotational (like a tradi‐
1450 tional floppy or hard disk). Returns false if the disk has no penalty
1451 for random access (like an SSD or RAM disk).
1452 This call does not block, because it returns data that is saved in the
1454 handle from the NBD protocol handshake.
1455 val can_trim : t -> bool
1459 NBD.can_trim t
1462 does the server support the trim command?
1464 Returns true if the server supports the trim command (see nbd_trim(3),
1466 nbd_aio_trim(3)). Returns false if the server does not.
1467 This call does not block, because it returns data that is saved in the
1469 handle from the NBD protocol handshake.
1470 val can_zero : t -> bool
1474 NBD.can_zero t
1477 does the server support the zero command?
1479 Returns true if the server supports the zero command (see nbd_zero(3),
1481 nbd_aio_zero(3)). Returns false if the server does not.
1482 This call does not block, because it returns data that is saved in the
1484 handle from the NBD protocol handshake.
1485 val can_fast_zero : t -> bool
1489 NBD.can_fast_zero t
1492 does the server support the fast zero flag?
1494 Returns true if the server supports the use of the
1496 "LIBNBD_CMD_FLAG_FAST_ZERO" flag to the zero command (see nbd_zero(3),
1497 nbd_aio_zero(3)). Returns false if the server does not.
1498 This call does not block, because it returns data that is saved in the
1500 handle from the NBD protocol handshake.
1501 val can_df : t -> bool
1505 NBD.can_df t
1508 does the server support the don't fragment flag to pread?
1510 Returns true if the server supports structured reads with an ability to
1512 request a non-fragmented read (see nbd_pread_structured(3),
1513 nbd_aio_pread_structured(3)). Returns false if the server either lacks
1514 structured reads or if it does not support a non-fragmented read re‐
1515 quest.
1516 This call does not block, because it returns data that is saved in the
1518 handle from the NBD protocol handshake.
1519 val can_multi_conn : t -> bool
1523 NBD.can_multi_conn t
1526 does the server support multi-conn?
1528 Returns true if the server supports multi-conn. Returns false if the
1530 server does not.
1531 It is not safe to open multiple handles connecting to the same server
1533 if you will write to the server and the server does not advertise
1534 multi-conn support. The safe way to check for this is to open one con‐
1535 nection, check this flag is true, then open further connections as re‐
1536 quired.
1537 This call does not block, because it returns data that is saved in the
1539 handle from the NBD protocol handshake.
1540 val can_cache : t -> bool
1544 NBD.can_cache t
1547 does the server support the cache command?
1549 Returns true if the server supports the cache command (see
1551 nbd_cache(3), nbd_aio_cache(3)). Returns false if the server does not.
1552 This call does not block, because it returns data that is saved in the
1554 handle from the NBD protocol handshake.
1555 val can_meta_context : t -> string -> bool
1559 NBD.can_meta_context t metacontext
1562 does the server support a specific meta context?
1564 Returns true if the server supports the given meta context (see
1566 nbd_add_meta_context(3)). Returns false if the server does not.
1567 The single parameter is the name of the metadata context, for example
1569 "LIBNBD_CONTEXT_BASE_ALLOCATION". <libnbd.h> includes defined con‐
1570 stants for well-known namespace contexts beginning with "LIBNBD_CON‐
1571 TEXT_", but you are free to pass in other contexts.
1572 This call does not block, because it returns data that is saved in the
1574 handle from the NBD protocol handshake.
1575 val get_protocol : t -> string
1579 NBD.get_protocol t
1582 return the NBD protocol variant
1584 Return the NBD protocol variant in use on the connection. At the moment
1586 this returns one of the strings "oldstyle", "newstyle" or "new‐
1587 style-fixed". Other strings might be returned in the future. Most mod‐
1588 ern NBD servers use "newstyle-fixed".
1589 This call does not block, because it returns data that is saved in the
1591 handle from the NBD protocol handshake.
1592 val get_size : t -> int64
1596 NBD.get_size t
1599 return the export size
1601 Returns the size in bytes of the NBD export.
1603 This call does not block, because it returns data that is saved in the
1605 handle from the NBD protocol handshake.
1606 val get_block_size : t -> SIZE.t -> int64
1610 NBD.get_block_size t size_type
1613 return a specific server block size constraint
1615 Returns a specific size constraint advertised by the server, if any. If
1617 the return is zero, the server did not advertise a constraint.
1618 "size_type" must be one of the following constraints:
1619 "LIBNBD_SIZE_MINIMUM" = 0 If non-zero, this will be a power of 2 be‐
1621 tween 1 and 64k; any client request that is not aligned in length or
1622 offset to this size is likely to fail with "EINVAL". The image size
1623 will generally also be a multiple of this value (if not, the final few
1624 bytes are inaccessible while obeying alignment constraints). If zero,
1625 it is safest to assume a minimum block size of 512, although many
1626 servers support a minimum block size of 1. If the server provides a
1627 constraint, then libnbd defaults to honoring that constraint
1628 client-side unless "LIBNBD_STRICT_ALIGN" is cleared in
1629 nbd_set_strict_mode(3).
1630 "LIBNBD_SIZE_PREFERRED" = 1 If non-zero, this is a power of 2 repre‐
1632 senting the preferred size for efficient I/O. Smaller requests may in‐
1633 cur overhead such as read-modify-write cycles that will not be present
1634 when using I/O that is a multiple of this value. This value may be
1635 larger than the size of the export. If zero, using 4k as a preferred
1636 block size tends to give decent performance.
1637 "LIBNBD_SIZE_MAXIMUM" = 2 If non-zero, this represents the maximum
1639 length that the server is willing to handle during nbd_pread(3) or
1640 nbd_pwrite(3). Other functions like nbd_zero(3) may still be able to
1641 use larger sizes. Note that this function returns what the server ad‐
1642 vertised, but libnbd itself imposes a maximum of 64M. If zero, some NBD
1643 servers will abruptly disconnect if a transaction involves more than
1644 32M.
1645 Future NBD extensions may result in additional "size_type" values. Note
1647 that by default, libnbd requests all available block sizes, but that a
1648 server may differ in what sizes it chooses to report if nbd_set_re‐
1649 quest_block_size(3) alters whether the client requests sizes.
1650 This call does not block, because it returns data that is saved in the
1652 handle from the NBD protocol handshake.
1653 val pread : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 -> unit
1657 NBD.pread t ?flags buf offset
1660 read from the NBD server
1662 Issue a read command to the NBD server for the range starting at "off‐
1664 set" and ending at "offset" + "count" - 1. NBD can only read all or
1665 nothing using this call. The call returns when the data has been read
1666 fully into "buf" or there is an error. See also nbd_pread_struc‐
1667 tured(3), if finer visibility is required into the server's replies, or
1668 if you want to use "LIBNBD_CMD_FLAG_DF".
1669 Note that libnbd currently enforces a maximum read buffer of 64MiB,
1671 even if the server would permit a larger buffer in a single transac‐
1672 tion; attempts to exceed this will result in an "ERANGE" error. The
1673 server may enforce a smaller limit, which can be learned with
1674 nbd_get_block_size(3).
1675 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
1677 tocol extensions).
1678 Note that if this command fails, and nbd_get_pread_initialize(3) re‐
1680 turns true, then libnbd sanitized "buf", but it is unspecified whether
1681 the contents of "buf" will read as zero or as partial results from the
1682 server. If nbd_get_pread_initialize(3) returns false, then libnbd did
1683 not sanitize "buf", and the contents are undefined on failure.
1684 By default, libnbd will reject attempts to use this function with pa‐
1686 rameters that are likely to result in server failure, such as request‐
1687 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1688 used to alter which scenarios should await a server reply rather than
1689 failing fast.
1690 val pread_structured : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 ->
1694 (bytes -> int64 -> int -> int Stdlib.ref -> int) -> unit
1695 NBD.pread_structured t ?flags buf offset chunk
1698 read from the NBD server
1700 Issue a read command to the NBD server for the range starting at "off‐
1702 set" and ending at "offset" + "count" - 1. The server's response may be
1703 subdivided into chunks which may arrive out of order before reassembly
1704 into the original buffer; the "chunk" callback is used for notification
1705 after each chunk arrives, and may perform additional sanity checking on
1706 the server's reply. The callback cannot call "nbd_*" APIs on the same
1707 handle since it holds the handle lock and will cause a deadlock. If the
1708 callback returns -1, and no earlier error has been detected, then the
1709 overall read command will fail with any non-zero value stored into the
1710 callback's "error" parameter (with a default of "EPROTO"); but any fur‐
1711 ther chunks will still invoke the callback.
1712 The "chunk" function is called once per chunk of data received, with
1714 the "user_data" passed to this function. The "subbuf" and "count" pa‐
1715 rameters represent the subset of the original buffer which has just
1716 been populated by results from the server (in C, "subbuf" always points
1717 within the original "buf"; but this guarantee may not extend to other
1718 language bindings). The "offset" parameter represents the absolute off‐
1719 set at which "subbuf" begins within the image (note that this is not
1720 the relative offset of "subbuf" within the original buffer "buf").
1721 Changes to "error" on output are ignored unless the callback fails. The
1722 input meaning of the "error" parameter is controlled by the "status"
1723 parameter, which is one of
1724 "LIBNBD_READ_DATA" = 1 "subbuf" was populated with "count" bytes of
1726 data. On input, "error" contains the errno value of any earlier de‐
1727 tected error, or zero.
1728 "LIBNBD_READ_HOLE" = 2 "subbuf" represents a hole, and contains "count"
1730 NUL bytes. On input, "error" contains the errno value of any earlier
1731 detected error, or zero.
1732 "LIBNBD_READ_ERROR" = 3 "count" is 0, so "subbuf" is unusable. On in‐
1734 put, "error" contains the errno value reported by the server as occur‐
1735 ring while reading that "offset", regardless if any earlier error has
1736 been detected.
1737 Future NBD extensions may permit other values for "status", but those
1739 will not be returned to a client that has not opted in to requesting
1740 such extensions. If the server is non-compliant, it is possible for the
1741 "chunk" function to be called more times than you expect or with
1742 "count" 0 for "LIBNBD_READ_DATA" or "LIBNBD_READ_HOLE". It is also pos‐
1743 sible that the "chunk" function is not called at all (in particular,
1744 "LIBNBD_READ_ERROR" is used only when an error is associated with a
1745 particular offset, and not when the server reports a generic error),
1746 but you are guaranteed that the callback was called at least once if
1747 the overall read succeeds. Libnbd does not validate that the server
1748 obeyed the requirement that a read call must not have overlapping
1749 chunks and must not succeed without enough chunks to cover the entire
1750 request.
1751 Note that libnbd currently enforces a maximum read buffer of 64MiB,
1753 even if the server would permit a larger buffer in a single transac‐
1754 tion; attempts to exceed this will result in an "ERANGE" error. The
1755 server may enforce a smaller limit, which can be learned with
1756 nbd_get_block_size(3).
1757 The "flags" parameter may be 0 for no flags, or may contain
1759 "LIBNBD_CMD_FLAG_DF" meaning that the server should not reply with more
1760 than one fragment (if that is supported - some servers cannot do this,
1761 see nbd_can_df(3)). Libnbd does not validate that the server actually
1762 obeys the flag.
1763 Note that if this command fails, and nbd_get_pread_initialize(3) re‐
1765 turns true, then libnbd sanitized "buf", but it is unspecified whether
1766 the contents of "buf" will read as zero or as partial results from the
1767 server. If nbd_get_pread_initialize(3) returns false, then libnbd did
1768 not sanitize "buf", and the contents are undefined on failure.
1769 By default, libnbd will reject attempts to use this function with pa‐
1771 rameters that are likely to result in server failure, such as request‐
1772 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1773 used to alter which scenarios should await a server reply rather than
1774 failing fast.
1775 val pwrite : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 -> unit
1779 NBD.pwrite t ?flags buf offset
1782 write to the NBD server
1784 Issue a write command to the NBD server, writing the data in "buf" to
1786 the range starting at "offset" and ending at "offset" + "count" - 1.
1787 NBD can only write all or nothing using this call. The call returns
1788 when the command has been acknowledged by the server, or there is an
1789 error. Note this will generally return an error if nbd_is_read_only(3)
1790 is true.
1791 Note that libnbd currently enforces a maximum write buffer of 64MiB,
1793 even if the server would permit a larger buffer in a single transac‐
1794 tion; attempts to exceed this will result in an "ERANGE" error. The
1795 server may enforce a smaller limit, which can be learned with
1796 nbd_get_block_size(3).
1797 The "flags" parameter may be 0 for no flags, or may contain
1799 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
1800 the data has been committed to permanent storage (if that is supported
1801 - some servers cannot do this, see nbd_can_fua(3)).
1802 By default, libnbd will reject attempts to use this function with pa‐
1804 rameters that are likely to result in server failure, such as request‐
1805 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1806 used to alter which scenarios should await a server reply rather than
1807 failing fast.
1808 val shutdown : ?flags:SHUTDOWN.t list -> t -> unit
1812 NBD.shutdown t ?flags
1815 disconnect from the NBD server
1817 Issue the disconnect command to the NBD server. This is a nice way to
1819 tell the server we are going away, but from the client's point of view
1820 has no advantage over abruptly closing the connection (see
1821 nbd_close(3)).
1822 This function works whether or not the handle is ready for transmission
1824 of commands. If more fine-grained control is needed, see nbd_aio_dis‐
1825 connect(3).
1826 The "flags" argument is a bitmask, including zero or more of the fol‐
1828 lowing shutdown flags:
1829 "LIBNBD_SHUTDOWN_ABANDON_PENDING" = 0x10000 If there are any pending
1831 requests which have not yet been sent to the server (see
1832 nbd_aio_in_flight(3)), abandon them without sending them to the server,
1833 rather than the usual practice of issuing those commands before inform‐
1834 ing the server of the intent to disconnect.
1835 For convenience, the constant "LIBNBD_SHUTDOWN_MASK" is available to
1837 describe all shutdown flags recognized by this build of libnbd. A fu‐
1838 ture version of the library may add new flags.
1839 val flush : ?flags:CMD_FLAG.t list -> t -> unit
1843 NBD.flush t ?flags
1846 send flush command to the NBD server
1848 Issue the flush command to the NBD server. The function should return
1850 when all write commands which have completed have been committed to
1851 permanent storage on the server. Note this will generally return an er‐
1852 ror if nbd_can_flush(3) is false.
1853 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
1855 tocol extensions).
1856 By default, libnbd will reject attempts to use this function with pa‐
1858 rameters that are likely to result in server failure, such as request‐
1859 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1860 used to alter which scenarios should await a server reply rather than
1861 failing fast.
1862 val trim : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
1866 NBD.trim t ?flags count offset
1869 send trim command to the NBD server
1871 Issue a trim command to the NBD server, which if supported by the
1873 server causes a hole to be punched in the backing store starting at
1874 "offset" and ending at "offset" + "count" - 1. The call returns when
1875 the command has been acknowledged by the server, or there is an error.
1876 Note this will generally return an error if nbd_can_trim(3) is false or
1877 nbd_is_read_only(3) is true.
1878 Note that not all servers can support a "count" of 4GiB or larger. The
1880 NBD protocol does not yet have a way for a client to learn if the
1881 server will enforce an even smaller maximum trim size, although a fu‐
1882 ture extension may add a constraint visible in nbd_get_block_size(3).
1883 The "flags" parameter may be 0 for no flags, or may contain
1885 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
1886 the data has been committed to permanent storage (if that is supported
1887 - some servers cannot do this, see nbd_can_fua(3)).
1888 By default, libnbd will reject attempts to use this function with pa‐
1890 rameters that are likely to result in server failure, such as request‐
1891 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1892 used to alter which scenarios should await a server reply rather than
1893 failing fast.
1894 val cache : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
1898 NBD.cache t ?flags count offset
1901 send cache (prefetch) command to the NBD server
1903 Issue the cache (prefetch) command to the NBD server, which if sup‐
1905 ported by the server causes data to be prefetched into faster storage
1906 by the server, speeding up a subsequent nbd_pread(3) call. The server
1907 can also silently ignore this command. Note this will generally return
1908 an error if nbd_can_cache(3) is false.
1909 Note that not all servers can support a "count" of 4GiB or larger. The
1911 NBD protocol does not yet have a way for a client to learn if the
1912 server will enforce an even smaller maximum cache size, although a fu‐
1913 ture extension may add a constraint visible in nbd_get_block_size(3).
1914 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
1916 tocol extensions).
1917 By default, libnbd will reject attempts to use this function with pa‐
1919 rameters that are likely to result in server failure, such as request‐
1920 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1921 used to alter which scenarios should await a server reply rather than
1922 failing fast.
1923 val zero : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
1927 NBD.zero t ?flags count offset
1930 send write zeroes command to the NBD server
1932 Issue a write zeroes command to the NBD server, which if supported by
1934 the server causes a zeroes to be written efficiently starting at "off‐
1935 set" and ending at "offset"
1936 -"count" - 1. The call returns when the command has been acknowledged
1938 by the server, or there is an error. Note this will generally return
1939 an error if nbd_can_zero(3) is false or nbd_is_read_only(3) is true.
1940 Note that not all servers can support a "count" of 4GiB or larger. The
1942 NBD protocol does not yet have a way for a client to learn if the
1943 server will enforce an even smaller maximum zero size, although a fu‐
1944 ture extension may add a constraint visible in nbd_get_block_size(3).
1945 Also, some servers may permit a larger zero request only when the
1946 "LIBNBD_CMD_FLAG_FAST_ZERO" is in use.
1947 The "flags" parameter may be 0 for no flags, or may contain
1949 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
1950 the data has been committed to permanent storage (if that is supported
1951 - some servers cannot do this, see nbd_can_fua(3)),
1952 "LIBNBD_CMD_FLAG_NO_HOLE" meaning that the server should favor writing
1953 actual allocated zeroes over punching a hole, and/or
1954 "LIBNBD_CMD_FLAG_FAST_ZERO" meaning that the server must fail quickly
1955 if writing zeroes is no faster than a normal write (if that is sup‐
1956 ported - some servers cannot do this, see nbd_can_fast_zero(3)).
1957 By default, libnbd will reject attempts to use this function with pa‐
1959 rameters that are likely to result in server failure, such as request‐
1960 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1961 used to alter which scenarios should await a server reply rather than
1962 failing fast.
1963 val block_status : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 ->
1967 (string -> int64 -> int64 array -> int Stdlib.ref -> int) -> unit
1968 NBD.block_status t ?flags count offset extent
1971 send block status command to the NBD server
1973 Issue the block status command to the NBD server. If supported by the
1975 server, this causes metadata context information about blocks beginning
1976 from the specified offset to be returned. The "count" parameter is a
1977 hint: the server may choose to return less status, or the final block
1978 may extend beyond the requested range. If multiple contexts are sup‐
1979 ported, the number of blocks and cumulative length of those blocks need
1980 not be identical between contexts.
1981 Note that not all servers can support a "count" of 4GiB or larger. The
1983 NBD protocol does not yet have a way for a client to learn if the
1984 server will enforce an even smaller maximum block status size, although
1985 a future extension may add a constraint visible in
1986 nbd_get_block_size(3).
1987 Depending on which metadata contexts were enabled before connecting
1989 (see nbd_add_meta_context(3)) and which are supported by the server
1990 (see nbd_can_meta_context(3)) this call returns information about ex‐
1991 tents by calling back to the "extent" function. The callback cannot
1992 call "nbd_*" APIs on the same handle since it holds the handle lock and
1993 will cause a deadlock. If the callback returns -1, and no earlier error
1994 has been detected, then the overall block status command will fail with
1995 any non-zero value stored into the callback's "error" parameter (with a
1996 default of "EPROTO"); but any further contexts will still invoke the
1997 callback.
1998 The "extent" function is called once per type of metadata available,
2000 with the "user_data" passed to this function. The "metacontext" parame‐
2001 ter is a string such as "base:allocation". The "entries" array is an
2002 array of pairs of integers with the first entry in each pair being the
2003 length (in bytes) of the block and the second entry being a sta‐
2004 tus/flags field which is specific to the metadata context. (The number
2005 of pairs passed to the function is "nr_entries/2".) The NBD protocol
2006 document in the section about "NBD_REPLY_TYPE_BLOCK_STATUS" describes
2007 the meaning of this array; for contexts known to libnbd, <libnbd.h>
2008 contains constants beginning with "LIBNBD_STATE_" that may help deci‐
2009 pher the values. On entry to the callback, the "error" parameter con‐
2010 tains the errno value of any previously detected error, but even if an
2011 earlier error was detected, the current "metacontext" and "entries" are
2012 valid.
2013 It is possible for the extent function to be called more times than you
2015 expect (if the server is buggy), so always check the "metacontext"
2016 field to ensure you are receiving the data you expect. It is also pos‐
2017 sible that the extent function is not called at all, even for metadata
2018 contexts that you requested. This indicates either that the server
2019 doesn't support the context or for some other reason cannot return the
2020 data.
2021 The "flags" parameter may be 0 for no flags, or may contain
2023 "LIBNBD_CMD_FLAG_REQ_ONE" meaning that the server should return only
2024 one extent per metadata context where that extent does not exceed
2025 "count" bytes; however, libnbd does not validate that the server obeyed
2026 the flag.
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 poll : t -> int -> int
2037 NBD.poll t timeout
2040 poll the handle once
2042 This is a simple implementation of poll(2) which is used internally by
2044 synchronous API calls. On success, it returns 0 if the "timeout" (in
2045 milliseconds) occurs, or 1 if the poll completed and the state machine
2046 progressed. Set "timeout" to -1 to block indefinitely (but be careful
2047 that eventual action is actually expected - for example, if the connec‐
2048 tion is established but there are no commands in flight, using an infi‐
2049 nite timeout will permanently block).
2050 This function is mainly useful as an example of how you might integrate
2052 libnbd with your own main loop, rather than being intended as something
2053 you would use.
2054 val aio_connect : t -> Unix.sockaddr -> unit
2058 NBD.aio_connect t addr
2061 connect to the NBD server
2063 Begin connecting to the NBD server. The "addr" and "addrlen" parameters
2065 specify the address of the socket to connect to.
2066 You can check if the connection is still connecting by calling
2068 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
2069 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
2070 tion.
2071 val aio_connect_uri : t -> string -> unit
2075 NBD.aio_connect_uri t uri
2078 connect to an NBD URI
2080 Begin connecting to the NBD URI "uri". Parameters behave as documented
2082 in nbd_connect_uri(3).
2083 You can check if the connection is still connecting by calling
2085 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
2086 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
2087 tion.
2088 val aio_connect_unix : t -> string -> unit
2092 NBD.aio_connect_unix t unixsocket
2095 connect to the NBD server over a Unix domain socket
2097 Begin connecting to the NBD server over Unix domain socket ("unix‐
2099 socket"). Parameters behave as documented in nbd_connect_unix(3).
2100 You can check if the connection is still connecting by calling
2102 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
2103 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
2104 tion.
2105 val aio_connect_vsock : t -> int64 -> int64 -> unit
2109 NBD.aio_connect_vsock t cid port
2112 connect to the NBD server over AF_VSOCK socket
2114 Begin connecting to the NBD server over the "AF_VSOCK" protocol to the
2116 server "cid:port". Parameters behave as documented in nbd_con‐
2117 nect_vsock(3).
2118 You can check if the connection is still connecting by calling
2120 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
2121 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
2122 tion.
2123 val aio_connect_tcp : t -> string -> string -> unit
2127 NBD.aio_connect_tcp t hostname port
2130 connect to the NBD server over a TCP port
2132 Begin connecting to the NBD server listening on "hostname:port". Param‐
2134 eters behave as documented in nbd_connect_tcp(3).
2135 You can check if the connection is still connecting by calling
2137 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
2138 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
2139 tion.
2140 val aio_connect_socket : t -> Unix.file_descr -> unit
2144 NBD.aio_connect_socket t sock
2147 connect directly to a connected socket
2149 Begin connecting to the connected socket "fd". Parameters behave as
2151 documented in nbd_connect_socket(3).
2152 You can check if the connection is still connecting by calling
2154 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
2155 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
2156 tion.
2157 val aio_connect_command : t -> string list -> unit
2161 NBD.aio_connect_command t argv
2164 connect to the NBD server
2166 Run the command as a subprocess and begin connecting to it over
2168 stdin/stdout. Parameters behave as documented in nbd_connect_com‐
2169 mand(3).
2170 You can check if the connection is still connecting by calling
2172 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
2173 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
2174 tion.
2175 val aio_connect_systemd_socket_activation : t -> string list -> unit
2179 NBD.aio_connect_systemd_socket_activation t argv
2182 connect using systemd socket activation
2184 Run the command as a subprocess and begin connecting to it using sys‐
2186 temd socket activation. Parameters behave as documented in nbd_con‐
2187 nect_systemd_socket_activation(3).
2188 You can check if the connection is still connecting by calling
2190 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
2191 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
2192 tion.
2193 val aio_opt_go : ?completion:(int Stdlib.ref -> int) -> t -> unit
2197 NBD.aio_opt_go t ?completion
2200 end negotiation and move on to using an export
2202 Request that the server finish negotiation and move on to serving the
2204 export previously specified by the most recent nbd_set_export_name(3)
2205 or nbd_connect_uri(3). This can only be used if nbd_set_opt_mode(3)
2206 enabled option mode.
2207 To determine when the request completes, wait for nbd_aio_is_connect‐
2209 ing(3) to return false. Or supply the optional "completion_callback"
2210 which will be invoked as described in "Completion callbacks" in
2211 libnbd(3), except that it is automatically retired regardless of return
2212 value. Note that directly detecting whether the server returns an error
2213 (as is done by the return value of the synchronous counterpart) is only
2214 possible with a completion callback; however it is also possible to in‐
2215 directly detect an error when nbd_aio_is_negotiating(3) returns true.
2216 val aio_opt_abort : t -> unit
2220 NBD.aio_opt_abort t
2223 end negotiation and close the connection
2225 Request that the server finish negotiation, gracefully if possible,
2227 then close the connection. This can only be used if nbd_set_opt_mode(3)
2228 enabled option mode.
2229 To determine when the request completes, wait for nbd_aio_is_connect‐
2231 ing(3) to return false.
2232 val aio_opt_list : ?completion:(int Stdlib.ref -> int) -> t -> (string
2236 -> string -> int) -> unit
2237 NBD.aio_opt_list t ?completion list
2240 request the server to list all exports during negotiation
2242 Request that the server list all exports that it supports. This can
2244 only be used if nbd_set_opt_mode(3) enabled option mode.
2245 To determine when the request completes, wait for nbd_aio_is_connect‐
2247 ing(3) to return false. Or supply the optional "completion_callback"
2248 which will be invoked as described in "Completion callbacks" in
2249 libnbd(3), except that it is automatically retired regardless of return
2250 value. Note that detecting whether the server returns an error (as is
2251 done by the return value of the synchronous counterpart) is only possi‐
2252 ble with a completion callback.
2253 val aio_opt_info : ?completion:(int Stdlib.ref -> int) -> t -> unit
2257 NBD.aio_opt_info t ?completion
2260 request the server for information about an export
2262 Request that the server supply information about the export name previ‐
2264 ously specified by the most recent nbd_set_export_name(3) or nbd_con‐
2265 nect_uri(3). This can only be used if nbd_set_opt_mode(3) enabled op‐
2266 tion mode.
2267 To determine when the request completes, wait for nbd_aio_is_connect‐
2269 ing(3) to return false. Or supply the optional "completion_callback"
2270 which will be invoked as described in "Completion callbacks" in
2271 libnbd(3), except that it is automatically retired regardless of return
2272 value. Note that detecting whether the server returns an error (as is
2273 done by the return value of the synchronous counterpart) is only possi‐
2274 ble with a completion callback.
2275 val aio_opt_list_meta_context : ?completion:(int Stdlib.ref -> int) ->
2279 t -> (string -> int) -> int
2280 NBD.aio_opt_list_meta_context t ?completion context
2283 request the server to list available meta contexts
2285 Request that the server list available meta contexts associated with
2287 the export previously specified by the most recent nbd_set_ex‐
2288 port_name(3) or nbd_connect_uri(3). This can only be used if
2289 nbd_set_opt_mode(3) enabled option mode.
2290 To determine when the request completes, wait for nbd_aio_is_connect‐
2292 ing(3) to return false. Or supply the optional "completion_callback"
2293 which will be invoked as described in "Completion callbacks" in
2294 libnbd(3), except that it is automatically retired regardless of return
2295 value. Note that detecting whether the server returns an error (as is
2296 done by the return value of the synchronous counterpart) is only possi‐
2297 ble with a completion callback.
2298 val aio_pread : ?completion:(int Stdlib.ref -> int) ->
2302 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> cookie
2303 NBD.aio_pread t ?completion ?flags buf offset
2306 read from the NBD server
2308 Issue a read command to the NBD server.
2310 To check if the command completed, call nbd_aio_command_completed(3).
2312 Or supply the optional "completion_callback" which will be invoked as
2313 described in "Completion callbacks" in libnbd(3).
2314 Note that you must ensure "buf" is valid until the command has com‐
2316 pleted. Furthermore, if the "error" parameter to "completion_callback"
2317 is set or if nbd_aio_command_completed(3) reports failure, and if
2318 nbd_get_pread_initialize(3) returns true, then libnbd sanitized "buf",
2319 but it is unspecified whether the contents of "buf" will read as zero
2320 or as partial results from the server. If nbd_get_pread_initialize(3)
2321 returns false, then libnbd did not sanitize "buf", and the contents are
2322 undefined on failure.
2323 Other parameters behave as documented in nbd_pread(3).
2325 By default, libnbd will reject attempts to use this function with pa‐
2327 rameters that are likely to result in server failure, such as request‐
2328 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2329 used to alter which scenarios should await a server reply rather than
2330 failing fast.
2331 val aio_pread_structured : ?completion:(int Stdlib.ref -> int) ->
2335 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> (bytes -> int64 ->
2336 int -> int Stdlib.ref -> int) -> cookie
2337 NBD.aio_pread_structured t ?completion ?flags buf offset chunk
2340 read from the NBD server
2342 Issue a read command to the NBD server.
2344 To check if the command completed, call nbd_aio_command_completed(3).
2346 Or supply the optional "completion_callback" which will be invoked as
2347 described in "Completion callbacks" in libnbd(3).
2348 Note that you must ensure "buf" is valid until the command has com‐
2350 pleted. Furthermore, if the "error" parameter to "completion_callback"
2351 is set or if nbd_aio_command_completed(3) reports failure, and if
2352 nbd_get_pread_initialize(3) returns true, then libnbd sanitized "buf",
2353 but it is unspecified whether the contents of "buf" will read as zero
2354 or as partial results from the server. If nbd_get_pread_initialize(3)
2355 returns false, then libnbd did not sanitize "buf", and the contents are
2356 undefined on failure.
2357 Other parameters behave as documented in nbd_pread_structured(3).
2359 By default, libnbd will reject attempts to use this function with pa‐
2361 rameters that are likely to result in server failure, such as request‐
2362 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2363 used to alter which scenarios should await a server reply rather than
2364 failing fast.
2365 val aio_pwrite : ?completion:(int Stdlib.ref -> int) ->
2369 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> cookie
2370 NBD.aio_pwrite t ?completion ?flags buf offset
2373 write to the NBD server
2375 Issue a write command to the NBD server.
2377 To check if the command completed, call nbd_aio_command_completed(3).
2379 Or supply the optional "completion_callback" which will be invoked as
2380 described in "Completion callbacks" in libnbd(3).
2381 Note that you must ensure "buf" is valid until the command has com‐
2383 pleted. Other parameters behave as documented in nbd_pwrite(3).
2384 By default, libnbd will reject attempts to use this function with pa‐
2386 rameters that are likely to result in server failure, such as request‐
2387 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2388 used to alter which scenarios should await a server reply rather than
2389 failing fast.
2390 val aio_disconnect : ?flags:CMD_FLAG.t list -> t -> unit
2394 NBD.aio_disconnect t ?flags
2397 disconnect from the NBD server
2399 Issue the disconnect command to the NBD server. This is not a normal
2401 command because NBD servers are not obliged to send a reply. Instead
2402 you should wait for nbd_aio_is_closed(3) to become true on the connec‐
2403 tion. Once this command is issued, you cannot issue any further com‐
2404 mands.
2405 Although libnbd does not prevent you from issuing this command while
2407 still waiting on the replies to previous commands, the NBD protocol
2408 recommends that you wait until there are no other commands in flight
2409 (see nbd_aio_in_flight(3)), to give the server a better chance at a
2410 clean shutdown.
2411 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
2413 tocol extensions). There is no direct synchronous counterpart; however,
2414 nbd_shutdown(3) will call this function if appropriate.
2415 val aio_flush : ?completion:(int Stdlib.ref -> int) ->
2419 ?flags:CMD_FLAG.t list -> t -> cookie
2420 NBD.aio_flush t ?completion ?flags
2423 send flush command to the NBD server
2425 Issue the flush command to the NBD server.
2427 To check if the command completed, call nbd_aio_command_completed(3).
2429 Or supply the optional "completion_callback" which will be invoked as
2430 described in "Completion callbacks" in libnbd(3).
2431 Other parameters behave as documented in nbd_flush(3).
2433 By default, libnbd will reject attempts to use this function with pa‐
2435 rameters that are likely to result in server failure, such as request‐
2436 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2437 used to alter which scenarios should await a server reply rather than
2438 failing fast.
2439 val aio_trim : ?completion:(int Stdlib.ref -> int) -> ?flags:CMD_FLAG.t
2443 list -> t -> int64 -> int64 -> cookie
2444 NBD.aio_trim t ?completion ?flags count offset
2447 send trim command to the NBD server
2449 Issue a trim command to the NBD server.
2451 To check if the command completed, call nbd_aio_command_completed(3).
2453 Or supply the optional "completion_callback" which will be invoked as
2454 described in "Completion callbacks" in libnbd(3).
2455 Other parameters behave as documented in nbd_trim(3).
2457 By default, libnbd will reject attempts to use this function with pa‐
2459 rameters that are likely to result in server failure, such as request‐
2460 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2461 used to alter which scenarios should await a server reply rather than
2462 failing fast.
2463 val aio_cache : ?completion:(int Stdlib.ref -> int) ->
2467 ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> cookie
2468 NBD.aio_cache t ?completion ?flags count offset
2471 send cache (prefetch) command to the NBD server
2473 Issue the cache (prefetch) command to the NBD server.
2475 To check if the command completed, call nbd_aio_command_completed(3).
2477 Or supply the optional "completion_callback" which will be invoked as
2478 described in "Completion callbacks" in libnbd(3).
2479 Other parameters behave as documented in nbd_cache(3).
2481 By default, libnbd will reject attempts to use this function with pa‐
2483 rameters that are likely to result in server failure, such as request‐
2484 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2485 used to alter which scenarios should await a server reply rather than
2486 failing fast.
2487 val aio_zero : ?completion:(int Stdlib.ref -> int) -> ?flags:CMD_FLAG.t
2491 list -> t -> int64 -> int64 -> cookie
2492 NBD.aio_zero t ?completion ?flags count offset
2495 send write zeroes command to the NBD server
2497 Issue a write zeroes command to the NBD server.
2499 To check if the command completed, call nbd_aio_command_completed(3).
2501 Or supply the optional "completion_callback" which will be invoked as
2502 described in "Completion callbacks" in libnbd(3).
2503 Other parameters behave as documented in nbd_zero(3).
2505 By default, libnbd will reject attempts to use this function with pa‐
2507 rameters that are likely to result in server failure, such as request‐
2508 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2509 used to alter which scenarios should await a server reply rather than
2510 failing fast.
2511 val aio_block_status : ?completion:(int Stdlib.ref -> int) ->
2515 ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> (string -> int64 ->
2516 int64 array -> int Stdlib.ref -> int) -> cookie
2517 NBD.aio_block_status t ?completion ?flags count offset extent
2520 send block status command to the NBD server
2522 Send the block status command to the NBD server.
2524 To check if the command completed, call nbd_aio_command_completed(3).
2526 Or supply the optional "completion_callback" which will be invoked as
2527 described in "Completion callbacks" in libnbd(3).
2528 Other parameters behave as documented in nbd_block_status(3).
2530 By default, libnbd will reject attempts to use this function with pa‐
2532 rameters that are likely to result in server failure, such as request‐
2533 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2534 used to alter which scenarios should await a server reply rather than
2535 failing fast.
2536 val aio_get_fd : t -> Unix.file_descr
2540 NBD.aio_get_fd t
2543 return file descriptor associated with this connection
2545 Return the underlying file descriptor associated with this connection.
2547 You can use this to check if the file descriptor is ready for reading
2548 or writing and call nbd_aio_notify_read(3) or nbd_aio_notify_write(3).
2549 See also nbd_aio_get_direction(3). Do not do anything else with the
2550 file descriptor.
2551 val aio_get_direction : t -> int
2555 NBD.aio_get_direction t
2558 return the read or write direction
2560 Return the current direction of this connection, which means whether we
2562 are next expecting to read data from the server, write data to the
2563 server, or both. It returns
2564 0 We are not expected to interact with the server file descriptor
2566 from the current state. It is not worth attempting to use poll(2); if
2567 the connection is not dead, then state machine progress must instead
2568 come from some other means such as nbd_aio_connect(3).
2569 "LIBNBD_AIO_DIRECTION_READ" = 1 We are expected next to read from the
2571 server. If using poll(2) you would set "events = POLLIN". If "revents"
2572 returns "POLLIN" or "POLLHUP" you would then call nbd_aio_no‐
2573 tify_read(3).
2574 Note that once libnbd reaches nbd_aio_is_ready(3), this direction is
2576 returned even when there are no commands in flight (see
2577 nbd_aio_in_flight(3)). In a single-threaded use of libnbd, it is not
2578 worth polling until after issuing a command, as otherwise the server
2579 will never wake up the poll. In a multi-threaded scenario, you can have
2580 one thread begin a polling loop prior to any commands, but any other
2581 thread that issues a command will need a way to kick the polling thread
2582 out of poll in case issuing the command changes the needed polling di‐
2583 rection. Possible ways to do this include polling for activity on a
2584 pipe-to-self, or using pthread_kill(3) to send a signal that is masked
2585 except during ppoll(2).
2586 "LIBNBD_AIO_DIRECTION_WRITE" = 2 We are expected next to write to the
2588 server. If using poll(2) you would set "events = POLLOUT". If "revents"
2589 returns "POLLOUT" you would then call nbd_aio_notify_write(3).
2590 "LIBNBD_AIO_DIRECTION_BOTH" = 3 We are expected next to either read or
2592 write to the server. If using poll(2) you would set "events =
2593 POLLIN|POLLOUT". If only one of "POLLIN" or "POLLOUT" is returned, then
2594 see above. However, if both are returned, it is better to call only
2595 nbd_aio_notify_read(3), as processing the server's reply may change the
2596 state of the connection and invalidate the need to write more commands.
2597 val aio_notify_read : t -> unit
2601 NBD.aio_notify_read t
2604 notify that the connection is readable
2606 Send notification to the state machine that the connection is readable.
2608 Typically this is called after your main loop has detected that the
2609 file descriptor associated with this connection is readable.
2610 val aio_notify_write : t -> unit
2614 NBD.aio_notify_write t
2617 notify that the connection is writable
2619 Send notification to the state machine that the connection is writable.
2621 Typically this is called after your main loop has detected that the
2622 file descriptor associated with this connection is writable.
2623 val aio_is_created : t -> bool
2627 NBD.aio_is_created t
2630 check if the connection has just been created
2632 Return true if this connection has just been created. This is the
2634 state before the handle has started connecting to a server. In this
2635 state the handle can start to be connected by calling functions such as
2636 nbd_aio_connect(3).
2637 val aio_is_connecting : t -> bool
2641 NBD.aio_is_connecting t
2644 check if the connection is connecting or handshaking
2646 Return true if this connection is connecting to the server or in the
2648 process of handshaking and negotiating options which happens before the
2649 handle becomes ready to issue commands (see nbd_aio_is_ready(3)).
2650 val aio_is_negotiating : t -> bool
2654 NBD.aio_is_negotiating t
2657 check if connection is ready to send handshake option
2659 Return true if this connection is ready to start another option negoti‐
2661 ation command while handshaking with the server. An option command will
2662 move back to the connecting state (see nbd_aio_is_connecting(3)). Note
2663 that this state cannot be reached unless requested by
2664 nbd_set_opt_mode(3), and even then it only works with newstyle servers;
2665 an oldstyle server will skip straight to nbd_aio_is_ready(3).
2666 val aio_is_ready : t -> bool
2670 NBD.aio_is_ready t
2673 check if the connection is in the ready state
2675 Return true if this connection is connected to the NBD server, the
2677 handshake has completed, and the connection is idle or waiting for a
2678 reply. In this state the handle is ready to issue commands.
2679 val aio_is_processing : t -> bool
2683 NBD.aio_is_processing t
2686 check if the connection is processing a command
2688 Return true if this connection is connected to the NBD server, the
2690 handshake has completed, and the connection is processing commands (ei‐
2691 ther writing out a request or reading a reply).
2692 Note the ready state (nbd_aio_is_ready(3)) is not included. In the
2694 ready state commands may be *in flight* (the *server* is processing
2695 them), but libnbd is not processing them.
2696 val aio_is_dead : t -> bool
2700 NBD.aio_is_dead t
2703 check if the connection is dead
2705 Return true if the connection has encountered a fatal error and is
2707 dead. In this state the handle may only be closed. There is no way to
2708 recover a handle from the dead state.
2709 val aio_is_closed : t -> bool
2713 NBD.aio_is_closed t
2716 check if the connection is closed
2718 Return true if the connection has closed. There is no way to reconnect
2720 a closed connection. Instead you must close the whole handle.
2721 val aio_command_completed : t -> int64 -> bool
2725 NBD.aio_command_completed t cookie
2728 check if the command completed
2730 Return true if the command completed. If this function returns true
2732 then the command was successful and it has been retired. Return false
2733 if the command is still in flight. This can also fail with an error in
2734 case the command failed (in this case the command is also retired). A
2735 command is retired either via this command, or by using a completion
2736 callback which returns 1.
2737 The "cookie" parameter is the positive unique 64 bit cookie for the
2739 command, as returned by a call such as nbd_aio_pread(3).
2740 val aio_peek_command_completed : t -> int64
2744 NBD.aio_peek_command_completed t
2747 check if any command has completed
2749 Return the unique positive 64 bit cookie of the first non-retired but
2751 completed command, 0 if there are in-flight commands but none of them
2752 are awaiting retirement, or -1 on error including when there are no
2753 in-flight commands. Any cookie returned by this function must still be
2754 passed to nbd_aio_command_completed(3) to actually retire the command
2755 and learn whether the command was successful.
2756 val aio_in_flight : t -> int
2760 NBD.aio_in_flight t
2763 check how many aio commands are still in flight
2765 Return the number of in-flight aio commands that are still awaiting a
2767 response from the server before they can be retired. If this returns a
2768 non-zero value when requesting a disconnect from the server (see
2769 nbd_aio_disconnect(3) and nbd_shutdown(3)), libnbd does not try to wait
2770 for those commands to complete gracefully; if the server strands com‐
2771 mands while shutting down, nbd_aio_command_completed(3) will report
2772 those commands as failed with a status of "ENOTCONN".
2773 val connection_state : t -> string
2777 NBD.connection_state t
2780 return string describing the state of the connection
2782 Returns a descriptive string for the state of the connection. This can
2784 be used for debugging or troubleshooting, but you should not rely on
2785 the state of connections since it may change in future versions.
2786 val get_package_name : t -> string
2790 NBD.get_package_name t
2793 return the name of the library
2795 Returns the name of the library, always "libnbd" unless the library was
2797 modified with another name at compile time.
2798 val get_version : t -> string
2802 NBD.get_version t
2805 return the version of the library
2807 Return the version of libnbd. This is returned as a string in the form
2809 "major.minor.release" where each of major, minor and release is a small
2810 positive integer. For example:
2811 minor ↓ "1.0.3" ↑ ↑ major release
2813 major = 0 The major number was 0 for the early experimental versions of
2815 libnbd where we still had an unstable API.
2816 major = 1 The major number is 1 for the versions of libnbd with a
2818 long-term stable API and ABI. It is not anticipated that major will be
2819 any number other than 1.
2820 minor = 0, 2, ... (even) The minor number is even for stable releases.
2822 minor = 1, 3, ... (odd) The minor number is odd for development ver‐
2824 sions. Note that new APIs added in a development version remain exper‐
2825 imental and subject to change in that branch until they appear in a
2826 stable release.
2827 release The release number is incremented for each release along a par‐
2829 ticular branch.
2830 val kill_subprocess : t -> int -> unit
2834 NBD.kill_subprocess t signum
2837 kill server running as a subprocess
2839 This call may be used to kill the server running as a subprocess that
2841 was previously created using nbd_connect_command(3). You do not need to
2842 use this call. It is only needed if the server does not exit when the
2843 socket is closed.
2844 The "signum" parameter is the optional signal number to send (see sig‐
2846 nal(7)). If "signum" is 0 then "SIGTERM" is sent.
2847 val supports_tls : t -> bool
2851 NBD.supports_tls t
2854 true if libnbd was compiled with support for TLS
2856 Returns true if libnbd was compiled with gnutls which is required to
2858 support TLS encryption, or false if not.
2859 val supports_uri : t -> bool
2863 NBD.supports_uri t
2866 true if libnbd was compiled with support for NBD URIs
2868 Returns true if libnbd was compiled with libxml2 which is required to
2870 support NBD URIs, or false if not.
2871 val get_uri : t -> string
2875 NBD.get_uri t
2878 construct an NBD URI for a connection
2880 This makes a best effort attempt to construct an NBD URI which could be
2882 used to connect back to the same server (using nbd_connect_uri(3)).
2883 In some cases there is not enough information in the handle to success‐
2885 fully create a URI (eg. if you connected with nbd_connect_socket(3)).
2886 In such cases the call returns "NULL" and further diagnostic informa‐
2887 tion is available via nbd_get_errno(3) and nbd_get_error(3) as usual.
2888 Even if a URI is returned it is not guaranteed to work, and it may not
2890 be optimal.
2891OCamldoc 2023-01-03 NBD(3)