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 stats_bytes_sent : t -> int64
244 NBD.stats_bytes_sent t
247 statistics of bytes sent over connection so far
249 Return the number of bytes that the client has sent to the server.
251 This tracks the plaintext bytes utilized by the NBD protocol; it may
253 differ from the number of bytes actually sent over the connection, par‐
254 ticularly when TLS is in use.
255 val stats_chunks_sent : t -> int64
259 NBD.stats_chunks_sent t
262 statistics of chunks sent over connection so far
264 Return the number of chunks that the client has sent to the server,
266 where a chunk is a group of bytes delineated by a magic number that
267 cannot be further subdivided without breaking the protocol.
268 This number does not necessarily relate to the number of API calls
270 made, nor to the number of TCP packets sent over the connection.
271 val stats_bytes_received : t -> int64
275 NBD.stats_bytes_received t
278 statistics of bytes received over connection so far
280 Return the number of bytes that the client has received from the
282 server.
283 This tracks the plaintext bytes utilized by the NBD protocol; it may
285 differ from the number of bytes actually received over the connection,
286 particularly when TLS is in use.
287 val stats_chunks_received : t -> int64
291 NBD.stats_chunks_received t
294 statistics of chunks received over connection so far
296 Return the number of chunks that the client has received from the
298 server, where a chunk is a group of bytes delineated by a magic number
299 that cannot be further subdivided without breaking the protocol.
300 This number does not necessarily relate to the number of API calls
302 made, nor to the number of TCP packets received over the connection.
303 val set_handle_name : t -> string -> unit
307 NBD.set_handle_name t handle_name
310 set the handle name
312 Handles have a name which is unique within the current process. The
314 handle name is used in debug output.
315 Handle names are normally generated automatically and have the form
317 "nbd1", "nbd2", etc., but you can optionally use this call to give the
318 handles a name which is meaningful for your application to make debug‐
319 ging output easier to understand.
320 val get_handle_name : t -> string
324 NBD.get_handle_name t
327 get the handle name
329 Get the name of the handle. If it was previously set by calling
331 nbd_set_handle_name(3) then this returns the name that was set. Other‐
332 wise it will return a generic name like "nbd1", "nbd2", etc.
333 val set_private_data : t -> int -> int
337 NBD.set_private_data t private_data
340 set the per-handle private data
342 Handles contain a private data field for applications to use for any
344 purpose.
345 When calling libnbd from C, the type of this field is "uintptr_t" so it
347 can be used to store an unsigned integer or a pointer.
348 In non-C bindings it can be used to store an unsigned integer.
350 This function sets the value of this field and returns the old value
352 (or 0 if it was not previously set).
353 val get_private_data : t -> int
357 NBD.get_private_data t
360 get the per-handle private data
362 Return the value of the private data field set previously by a call to
364 nbd_set_private_data(3) (or 0 if it was not previously set).
365 val set_export_name : t -> string -> unit
369 NBD.set_export_name t export_name
372 set the export name
374 For servers which require an export name or can serve different content
376 on different exports, set the "export_name" to connect to. The default
377 is the empty string "".
378 This is only relevant when connecting to servers using the newstyle
380 protocol as the oldstyle protocol did not support export names. The NBD
381 protocol limits export names to 4096 bytes, but servers may not support
382 the full length. The encoding of export names is always UTF-8.
383 When option mode is not in use, the export name must be set before be‐
385 ginning a connection. However, when nbd_set_opt_mode(3) has enabled op‐
386 tion mode, it is possible to change the export name prior to
387 nbd_opt_go(3). In particular, the use of nbd_opt_list(3) during negoti‐
388 ation can be used to determine a name the server is likely to accept,
389 and nbd_opt_info(3) can be used to learn details about an export before
390 connecting.
391 This call may be skipped if using nbd_connect_uri(3) to connect to a
393 URI that includes an export name.
394 val get_export_name : t -> string
398 NBD.get_export_name t
401 get the export name
403 Get the export name associated with the handle. This is the name that
405 libnbd requests; see nbd_get_canonical_export_name(3) for determining
406 if the server has a different canonical name for the given export (most
407 common when requesting the default export name of an empty string "")
408 val set_request_block_size : t -> bool -> unit
412 NBD.set_request_block_size t request
415 control whether NBD_OPT_GO requests block size
417 By default, when connecting to an export, libnbd requests that the
419 server report any block size restrictions. The NBD protocol states that
420 a server may supply block sizes regardless of whether the client re‐
421 quests them, and libnbd will report those block sizes (see
422 nbd_get_block_size(3)); conversely, if a client does not request block
423 sizes, the server may reject the connection instead of dealing with a
424 client sending unaligned requests. This function makes it possible to
425 test server behavior by emulating older clients.
426 Note that even when block size is requested, the server is not obli‐
428 gated to provide any. Furthermore, if block sizes are provided (whether
429 or not the client requested them), libnbd enforces alignment to those
430 sizes unless nbd_set_strict_mode(3) is used to bypass client-side
431 safety checks.
432 val get_request_block_size : t -> bool
436 NBD.get_request_block_size t
439 see if NBD_OPT_GO requests block size
441 Return the state of the block size request flag on this handle.
443 val set_full_info : t -> bool -> unit
447 NBD.set_full_info t request
450 control whether NBD_OPT_GO requests extra details
452 By default, when connecting to an export, libnbd only requests the de‐
454 tails it needs to service data operations. The NBD protocol says that a
455 server can supply optional information, such as a canonical name of the
456 export (see nbd_get_canonical_export_name(3)) or a description of the
457 export (see nbd_get_export_description(3)), but that a hint from the
458 client makes it more likely for this extra information to be provided.
459 This function controls whether libnbd will provide that hint.
460 Note that even when full info is requested, the server is not obligated
462 to reply with all information that libnbd requested. Similarly, libnbd
463 will ignore any optional server information that libnbd has not yet
464 been taught to recognize. Furthermore, the hint to request block sizes
465 is independently controlled via nbd_set_request_block_size(3).
466 val get_full_info : t -> bool
470 NBD.get_full_info t
473 see if NBD_OPT_GO requests extra details
475 Return the state of the full info request flag on this handle.
477 val get_canonical_export_name : t -> string
481 NBD.get_canonical_export_name t
484 return the canonical export name, if the server has one
486 The NBD protocol permits a server to report an optional canonical ex‐
488 port name, which may differ from the client's request (as set by
489 nbd_set_export_name(3) or nbd_connect_uri(3)). This function accesses
490 any name returned by the server; it may be the same as the client re‐
491 quest, but is more likely to differ when the client requested a connec‐
492 tion to the default export name (an empty string "").
493 Some servers are unlikely to report a canonical name unless the client
495 specifically hinted about wanting it, via nbd_set_full_info(3).
496 val get_export_description : t -> string
500 NBD.get_export_description t
503 return the export description, if the server has one
505 The NBD protocol permits a server to report an optional export descrip‐
507 tion. This function reports any description returned by the server.
508 Some servers are unlikely to report a description unless the client
510 specifically hinted about wanting it, via nbd_set_full_info(3). For
511 qemu-nbd(8), a description is set with *-D*.
512 val set_tls : t -> TLS.t -> unit
516 NBD.set_tls t tls
519 enable or require TLS (authentication and encryption)
521 Enable or require TLS (authenticated and encrypted connections) to the
523 NBD server. The possible settings are:
524 "LIBNBD_TLS_DISABLE" Disable TLS. (The default setting, unless using
526 nbd_connect_uri(3) with a URI that requires TLS).
527 This setting is also necessary if you use nbd_set_opt_mode(3) and want
529 to interact in plaintext with a server that implements the NBD proto‐
530 col's "SELECTIVETLS" mode, prior to enabling TLS with nbd_opt_start‐
531 tls(3). Most NBD servers with TLS support prefer the NBD protocol's
532 "FORCEDTLS" mode, so this sort of manual interaction tends to be useful
533 mainly during integration testing.
534 "LIBNBD_TLS_ALLOW" Enable TLS if possible.
536 This option is insecure (or best effort) in that in some cases it will
538 fall back to an unencrypted and/or unauthenticated connection if TLS
539 could not be established. Use "LIBNBD_TLS_REQUIRE" below if the connec‐
540 tion must be encrypted.
541 Some servers will drop the connection if TLS fails so fallback may not
543 be possible.
544 "LIBNBD_TLS_REQUIRE" Require an encrypted and authenticated TLS connec‐
546 tion. Always fail to connect if the connection is not encrypted and au‐
547 thenticated.
548 As well as calling this you may also need to supply the path to the
550 certificates directory (nbd_set_tls_certificates(3)), the username
551 (nbd_set_tls_username(3)) and/or the Pre-Shared Keys (PSK) file
552 (nbd_set_tls_psk_file(3)). For now, when using nbd_connect_uri(3), any
553 URI query parameters related to TLS are not handled automatically. Set‐
554 ting the level higher than zero will fail if libnbd was not compiled
555 against gnutls; you can test whether this is the case with nbd_sup‐
556 ports_tls(3).
557 val get_tls : t -> TLS.t
561 NBD.get_tls t
564 get the TLS request setting
566 Get the TLS request setting.
568 Note: If you want to find out if TLS was actually negotiated on a par‐
570 ticular connection use nbd_get_tls_negotiated(3) instead.
571 val get_tls_negotiated : t -> bool
575 NBD.get_tls_negotiated t
578 find out if TLS was negotiated on a connection
580 After connecting you may call this to find out if the connection is us‐
582 ing TLS.
583 This is normally useful only if you set the TLS request mode to
585 "LIBNBD_TLS_ALLOW" (see nbd_set_tls(3)), because in this mode we try to
586 use TLS but fall back to unencrypted if it was not available. This
587 function will tell you if TLS was negotiated or not.
588 In "LIBNBD_TLS_REQUIRE" mode (the most secure) the connection would
590 have failed if TLS could not be negotiated. With "LIBNBD_TLS_DISABLE"
591 mode, TLS is not tried automatically; but if the NBD server uses the
592 less-common "SELECTIVETLS" mode, this function reports whether a manual
593 nbd_opt_starttls(3) enabled TLS or if the connection is still plain‐
594 text.
595 val set_tls_certificates : t -> string -> unit
599 NBD.set_tls_certificates t dir
602 set the path to the TLS certificates directory
604 Set the path to the TLS certificates directory. If not set and TLS is
606 used then a compiled in default is used. For root this is
607 "/etc/pki/libnbd/". For non-root this is "$HOME/.pki/libnbd" and
608 "$HOME/.config/pki/libnbd". If none of these directories can be found
609 then the system trusted CAs are used.
610 This function may be called regardless of whether TLS is supported, but
612 will have no effect unless nbd_set_tls(3) is also used to request or
613 require TLS.
614 val set_tls_verify_peer : t -> bool -> unit
618 NBD.set_tls_verify_peer t verify
621 set whether we verify the identity of the server
623 Set this flag to control whether libnbd will verify the identity of the
625 server from the server's certificate and the certificate authority.
626 This defaults to true when connecting to TCP servers using TLS certifi‐
627 cate authentication, and false otherwise.
628 This function may be called regardless of whether TLS is supported, but
630 will have no effect unless nbd_set_tls(3) is also used to request or
631 require TLS.
632 val get_tls_verify_peer : t -> bool
636 NBD.get_tls_verify_peer t
639 get whether we verify the identity of the server
641 Get the verify peer flag.
643 val set_tls_username : t -> string -> unit
647 NBD.set_tls_username t username
650 set the TLS username
652 Set the TLS client username. This is used if authenticating with PSK
654 over TLS is enabled. If not set then the local username is used.
655 This function may be called regardless of whether TLS is supported, but
657 will have no effect unless nbd_set_tls(3) is also used to request or
658 require TLS.
659 val get_tls_username : t -> string
663 NBD.get_tls_username t
666 get the current TLS username
668 Get the current TLS username.
670 val set_tls_psk_file : t -> string -> unit
674 NBD.set_tls_psk_file t filename
677 set the TLS Pre-Shared Keys (PSK) filename
679 Set the TLS Pre-Shared Keys (PSK) filename. This is used if trying to
681 authenticate to the server using with a pre-shared key. There is no de‐
682 fault so if this is not set then PSK authentication cannot be used to
683 connect to the server.
684 This function may be called regardless of whether TLS is supported, but
686 will have no effect unless nbd_set_tls(3) is also used to request or
687 require TLS.
688 val set_request_structured_replies : t -> bool -> unit
692 NBD.set_request_structured_replies t request
695 control use of structured replies
697 By default, libnbd tries to negotiate structured replies with the
699 server, as this protocol extension must be in use before
700 nbd_can_meta_context(3) or nbd_can_df(3) can return true. However, for
701 integration testing, it can be useful to clear this flag rather than
702 find a way to alter the server to fail the negotiation request. It is
703 also useful to set this to false prior to using nbd_set_opt_mode(3) if
704 it is desired to control when to send nbd_opt_structured_reply(3) dur‐
705 ing negotiation.
706 val get_request_structured_replies : t -> bool
710 NBD.get_request_structured_replies t
713 see if structured replies are attempted
715 Return the state of the request structured replies flag on this handle.
717 Note: If you want to find out if structured replies were actually nego‐
719 tiated on a particular connection use nbd_get_structured_replies_nego‐
720 tiated(3) instead.
721 val get_structured_replies_negotiated : t -> bool
725 NBD.get_structured_replies_negotiated t
728 see if structured replies are in use
730 After connecting you may call this to find out if the connection is us‐
732 ing structured replies. Note that this setting is sticky; this can re‐
733 turn true even after a second nbd_opt_structured_reply(3) returns false
734 because the server detected a duplicate request.
735 val set_request_meta_context : t -> bool -> unit
739 NBD.set_request_meta_context t request
742 control whether connect automatically requests meta contexts
744 This function controls whether the act of connecting to an export (all
746 "nbd_connect_*" calls when nbd_set_opt_mode(3) is false, or
747 nbd_opt_go(3) and nbd_opt_info(3) when option mode is enabled) will
748 also try to issue NBD_OPT_SET_META_CONTEXT when the server supports
749 structured replies and any contexts were registered by
750 nbd_add_meta_context(3). The default setting is true; however the extra
751 step of negotiating meta contexts is not always desirable: performing
752 both info and go on the same export works without needing to re-negoti‐
753 ate contexts on the second call; integration testing of other servers
754 may benefit from manual invocation of nbd_opt_set_meta_context(3) at
755 other times in the negotiation sequence; and even when using just
756 nbd_opt_info(3), it can be faster to collect the server's results by
757 relying on the callback function passed to nbd_opt_list_meta_context(3)
758 than a series of post-process calls to nbd_can_meta_context(3).
759 Note that this control has no effect if the server does not negotiate
761 structured replies, or if the client did not request any contexts via
762 nbd_add_meta_context(3). Setting this control to false may cause
763 nbd_block_status(3) to fail.
764 val get_request_meta_context : t -> bool
768 NBD.get_request_meta_context t
771 see if connect automatically requests meta contexts
773 Return the state of the automatic meta context request flag on this
775 handle.
776 val set_handshake_flags : t -> HANDSHAKE_FLAG.t list -> unit
780 NBD.set_handshake_flags t flags
783 control use of handshake flags
785 By default, libnbd tries to negotiate all possible handshake flags that
787 are also supported by the server, since omitting a handshake flag can
788 prevent the use of other functionality such as TLS encryption or struc‐
789 tured replies. However, for integration testing, it can be useful to
790 reduce the set of flags supported by the client to test that a particu‐
791 lar server can handle various clients that were compliant to older ver‐
792 sions of the NBD specification.
793 The "flags" argument is a bitmask, including zero or more of the fol‐
795 lowing handshake flags:
796 "LIBNBD_HANDSHAKE_FLAG_FIXED_NEWSTYLE" = 1 The server gracefully han‐
798 dles unknown option requests from the client, rather than disconnect‐
799 ing. Without this flag, a client cannot safely request to use exten‐
800 sions such as TLS encryption or structured replies, as the request may
801 cause an older server to drop the connection.
802 "LIBNBD_HANDSHAKE_FLAG_NO_ZEROES" = 2 If the client is forced to use
804 "NBD_OPT_EXPORT_NAME" instead of the preferred "NBD_OPT_GO", this flag
805 allows the server to send fewer all-zero padding bytes over the connec‐
806 tion.
807 For convenience, the constant "LIBNBD_HANDSHAKE_FLAG_MASK" is available
809 to describe all flags supported by this build of libnbd. Future NBD ex‐
810 tensions may add further flags, which in turn may be enabled by default
811 in newer libnbd. As such, when attempting to disable only one specific
812 bit, it is wiser to first call nbd_get_handshake_flags(3) and modify
813 that value, rather than blindly setting a constant value.
814 val get_handshake_flags : t -> HANDSHAKE_FLAG.t list
818 NBD.get_handshake_flags t
821 see which handshake flags are supported
823 Return the state of the handshake flags on this handle. When the han‐
825 dle has not yet completed a connection (see nbd_aio_is_created(3)),
826 this returns the flags that the client is willing to use, provided the
827 server also advertises those flags. After the connection is ready (see
828 nbd_aio_is_ready(3)), this returns the flags that were actually agreed
829 on between the server and client. If the NBD protocol defines new
830 handshake flags, then the return value from a newer library version may
831 include bits that were undefined at the time of compilation.
832 val set_pread_initialize : t -> bool -> unit
836 NBD.set_pread_initialize t request
839 control whether libnbd pre-initializes read buffers
841 By default, libnbd will pre-initialize the contents of a buffer passed
843 to calls such as nbd_pread(3) to all zeroes prior to checking for any
844 other errors, so that even if a client application passed in an unini‐
845 tialized buffer but fails to check for errors, it will not result in a
846 potential security risk caused by an accidental leak of prior heap con‐
847 tents (see CVE-2022-0485 in libnbd-security(3) for an example of a se‐
848 curity hole in an application built against an earlier version of
849 libnbd that lacked consistent pre-initialization). However, for a
850 client application that has audited that an uninitialized buffer is
851 never dereferenced, or which performs its own pre-initialization,
852 libnbd's sanitization efforts merely pessimize performance (although
853 the time spent in pre-initialization may pale in comparison to time
854 spent waiting on network packets).
855 Calling this function with "request" set to false tells libnbd to skip
857 the buffer initialization step in read commands.
858 val get_pread_initialize : t -> bool
862 NBD.get_pread_initialize t
865 see whether libnbd pre-initializes read buffers
867 Return whether libnbd performs a pre-initialization of a buffer passed
869 to nbd_pread(3) and similar to all zeroes, as set by nbd_set_pread_ini‐
870 tialize(3).
871 val set_strict_mode : t -> STRICT.t list -> unit
875 NBD.set_strict_mode t flags
878 control how strictly to follow NBD protocol
880 By default, libnbd tries to detect requests that would trigger unde‐
882 fined behavior in the NBD protocol, and rejects them client side with‐
883 out causing any network traffic, rather than risking undefined server
884 behavior. However, for integration testing, it can be handy to relax
885 the strictness of libnbd, to coerce it into sending such requests over
886 the network for testing the robustness of the server in dealing with
887 such traffic.
888 The "flags" argument is a bitmask, including zero or more of the fol‐
890 lowing strictness flags:
891 "LIBNBD_STRICT_COMMANDS" = 0x1 If set, this flag rejects client re‐
893 quests that do not comply with the set of advertised server flags (for
894 example, attempting a write on a read-only server, or attempting to use
895 "LIBNBD_CMD_FLAG_FUA" when nbd_can_fua(3) returned false). If clear,
896 this flag relies on the server to reject unexpected commands.
897 "LIBNBD_STRICT_FLAGS" = 0x2 If set, this flag rejects client requests
899 that attempt to set a command flag not recognized by libnbd (those out‐
900 side of "LIBNBD_CMD_FLAG_MASK"), or a flag not normally associated with
901 a command (such as using "LIBNBD_CMD_FLAG_FUA" on a read command). If
902 clear, all flags are sent on to the server, even if sending such a flag
903 may cause the server to change its reply in a manner that confuses
904 libnbd, perhaps causing deadlock or ending the connection.
905 Flags that are known by libnbd as associated with a given command (such
907 as "LIBNBD_CMD_FLAG_DF" for nbd_pread_structured(3) gated by
908 nbd_can_df(3)) are controlled by "LIBNBD_STRICT_COMMANDS" instead.
909 Note that the NBD protocol only supports 16 bits of command flags, even
911 though the libnbd API uses "uint32_t"; bits outside of the range per‐
912 mitted by the protocol are always a client-side error.
913 "LIBNBD_STRICT_BOUNDS" = 0x4 If set, this flag rejects client requests
915 that would exceed the export bounds without sending any traffic to the
916 server. If clear, this flag relies on the server to detect
917 out-of-bounds requests.
918 "LIBNBD_STRICT_ZERO_SIZE" = 0x8 If set, this flag rejects client re‐
920 quests with length 0. If clear, this permits zero-length requests to
921 the server, which may produce undefined results.
922 "LIBNBD_STRICT_ALIGN" = 0x10 If set, and the server provided minimum
924 block sizes (see "LIBNBD_SIZE_MINIMUM" for nbd_get_block_size(3)), this
925 flag rejects client requests that do not have length and offset aligned
926 to the server's minimum requirements. If clear, unaligned requests are
927 sent to the server, where it is up to the server whether to honor or
928 reject the request.
929 "LIBNBD_STRICT_PAYLOAD" = 0x20 If set, the client refuses to send a
931 command to the server with more than libnbd's outgoing payload maximum
932 (see "LIBNBD_SIZE_PAYLOAD" for nbd_get_block_size(3)), whether or not
933 the server advertised a block size maximum. If clear, oversize requests
934 up to 64MiB may be attempted, although requests larger than 32MiB are
935 liable to cause some servers to disconnect.
936 For convenience, the constant "LIBNBD_STRICT_MASK" is available to de‐
938 scribe all strictness flags supported by this build of libnbd. Future
939 versions of libnbd may add further flags, which are likely to be en‐
940 abled by default for additional client-side filtering. As such, when
941 attempting to relax only one specific bit while keeping remaining
942 checks at the client side, it is wiser to first call
943 nbd_get_strict_mode(3) and modify that value, rather than blindly set‐
944 ting a constant value.
945 val get_strict_mode : t -> STRICT.t list
949 NBD.get_strict_mode t
952 see which strictness flags are in effect
954 Return flags indicating which protocol strictness items are being en‐
956 forced locally by libnbd rather than the server. The return value from
957 a newer library version may include bits that were undefined at the
958 time of compilation.
959 val set_opt_mode : t -> bool -> unit
963 NBD.set_opt_mode t enable
966 control option mode, for pausing during option negotiation
968 Set this flag to true in order to request that a connection command
970 "nbd_connect_*" will pause for negotiation options rather than proceed‐
971 ing all the way to the ready state, when communicating with a newstyle
972 server. This setting has no effect when connecting to an oldstyle
973 server.
974 Note that libnbd defaults to attempting "NBD_OPT_STARTTLS" and
976 "NBD_OPT_STRUCTURED_REPLY" before letting you control remaining negoti‐
977 ation steps; if you need control over these steps as well, first set
978 nbd_set_tls(3) to "LIBNBD_TLS_DISABLE" and nbd_set_request_struc‐
979 tured_replies(3) to false before starting the connection attempt.
980 When option mode is enabled, you have fine-grained control over which
982 options are negotiated, compared to the default of the server negotiat‐
983 ing everything on your behalf using settings made before starting the
984 connection. To leave the mode and proceed on to the ready state, you
985 must use nbd_opt_go(3) successfully; a failed nbd_opt_go(3) returns to
986 the negotiating state to allow a change of export name before trying
987 again. You may also use nbd_opt_abort(3) to end the connection without
988 finishing negotiation.
989 val get_opt_mode : t -> bool
993 NBD.get_opt_mode t
996 return whether option mode was enabled
998 Return true if option negotiation mode was enabled on this handle.
1000 val opt_go : t -> unit
1004 NBD.opt_go t
1007 end negotiation and move on to using an export
1009 Request that the server finish negotiation and move on to serving the
1011 export previously specified by the most recent nbd_set_export_name(3)
1012 or nbd_connect_uri(3). This can only be used if nbd_set_opt_mode(3)
1013 enabled option mode.
1014 By default, libnbd will automatically request all meta contexts regis‐
1016 tered by nbd_add_meta_context(3) as part of this call; but this can be
1017 suppressed with nbd_set_request_meta_context(3), particularly if
1018 nbd_opt_set_meta_context(3) was used earlier in the negotiation se‐
1019 quence.
1020 If this fails, the server may still be in negotiation, where it is pos‐
1022 sible to attempt another option such as a different export name; al‐
1023 though older servers will instead have killed the connection.
1024 val opt_abort : t -> unit
1028 NBD.opt_abort t
1031 end negotiation and close the connection
1033 Request that the server finish negotiation, gracefully if possible,
1035 then close the connection. This can only be used if nbd_set_opt_mode(3)
1036 enabled option mode.
1037 val opt_starttls : t -> bool
1041 NBD.opt_starttls t
1044 request the server to initiate TLS
1046 Request that the server initiate a secure TLS connection, by sending
1048 "NBD_OPT_STARTTLS". This can only be used if nbd_set_opt_mode(3) en‐
1049 abled option mode; furthermore, if you use nbd_set_tls(3) to request
1050 anything other than the default of "LIBNBD_TLS_DISABLE", then libnbd
1051 will have already attempted a TLS connection prior to allowing you con‐
1052 trol over option negotiation. This command is disabled if nbd_sup‐
1053 ports_tls(3) reports false.
1054 This function is mainly useful for integration testing of corner cases
1056 in server handling; in particular, misuse of this function when coupled
1057 with a server that is not careful about resetting stateful commands
1058 such as nbd_opt_structured_reply(3) could result in a security hole
1059 (see CVE-2021-3716 against nbdkit, for example). Thus, when security
1060 is a concern, you should instead prefer to use nbd_set_tls(3) with
1061 "LIBNBD_TLS_REQUIRE" and let libnbd negotiate TLS automatically.
1062 This function returns true if the server replies with success, false if
1064 the server replies with an error, and fails only if the server does not
1065 reply (such as for a loss of connection, which can include when the
1066 server rejects credentials supplied during the TLS handshake). Note
1067 that the NBD protocol documents that requesting TLS after it is already
1068 enabled is a client error; most servers will gracefully fail a second
1069 request, but that does not downgrade a TLS session that has already
1070 been established, as reported by nbd_get_tls_negotiated(3).
1071 val opt_structured_reply : t -> bool
1075 NBD.opt_structured_reply t
1078 request the server to enable structured replies
1080 Request that the server use structured replies, by sending
1082 "NBD_OPT_STRUCTURED_REPLY". This can only be used if
1083 nbd_set_opt_mode(3) enabled option mode; furthermore, libnbd defaults
1084 to automatically requesting this unless you use nbd_set_request_struc‐
1085 tured_replies(3) prior to connecting. This function is mainly useful
1086 for integration testing of corner cases in server handling.
1087 This function returns true if the server replies with success, false if
1089 the server replies with an error, and fails only if the server does not
1090 reply (such as for a loss of connection). Note that some servers fail a
1091 second request as redundant; libnbd assumes that once one request has
1092 succeeded, then structured replies are supported (as visible by
1093 nbd_get_structured_replies_negotiated(3)) regardless if later calls to
1094 this function return false.
1095 val opt_list : t -> (string -> string -> int) -> int
1099 NBD.opt_list t list
1102 request the server to list all exports during negotiation
1104 Request that the server list all exports that it supports. This can
1106 only be used if nbd_set_opt_mode(3) enabled option mode.
1107 The "list" function is called once per advertised export, with any
1109 "user_data" passed to this function, and with "name" and "description"
1110 supplied by the server. Many servers omit descriptions, in which case
1111 "description" will be an empty string. Remember that it is not safe to
1112 call nbd_set_export_name(3) from within the context of the callback
1113 function; rather, your code must copy any "name" needed for later use
1114 after this function completes. At present, the return value of the
1115 callback is ignored, although a return of -1 should be avoided.
1116 For convenience, when this function succeeds, it returns the number of
1118 exports that were advertised by the server.
1119 Not all servers understand this request, and even when it is under‐
1121 stood, the server might intentionally send an empty list to avoid being
1122 an information leak, may encounter a failure after delivering partial
1123 results, or may refuse to answer more than one query per connection in
1124 the interest of avoiding negotiation that does not resolve. Thus, this
1125 function may succeed even when no exports are reported, or may fail but
1126 have a non-empty list. Likewise, the NBD protocol does not specify an
1127 upper bound for the number of exports that might be advertised, so
1128 client code should be aware that a server may send a lengthy list.
1129 For nbd-server(1) you will need to allow clients to make list requests
1131 by adding "allowlist=true" to the " generic " section of
1132 /etc/nbd-server/config. For qemu-nbd(8), a description is set with
1133 *-D*.
1134 val opt_info : t -> unit
1138 NBD.opt_info t
1141 request the server for information about an export
1143 Request that the server supply information about the export name previ‐
1145 ously specified by the most recent nbd_set_export_name(3) or nbd_con‐
1146 nect_uri(3). This can only be used if nbd_set_opt_mode(3) enabled op‐
1147 tion mode.
1148 If successful, functions like nbd_is_read_only(3) and nbd_get_size(3)
1150 will report details about that export. If nbd_set_request_meta_con‐
1151 text(3) is set (the default) and structured replies were negotiated, it
1152 is also valid to use nbd_can_meta_context(3) after this call. However,
1153 it may be more efficient to clear that setting and manually utilize
1154 nbd_opt_list_meta_context(3) with its callback approach, for learning
1155 which contexts an export supports. In general, if nbd_opt_go(3) is
1156 called next, that call will likely succeed with the details remaining
1157 the same, although this is not guaranteed by all servers.
1158 Not all servers understand this request, and even when it is under‐
1160 stood, the server might fail the request even when a corresponding
1161 nbd_opt_go(3) would succeed.
1162 val opt_list_meta_context : t -> (string -> int) -> int
1166 NBD.opt_list_meta_context t context
1169 list available meta contexts, using implicit query list
1171 Request that the server list available meta contexts associated with
1173 the export previously specified by the most recent nbd_set_ex‐
1174 port_name(3) or nbd_connect_uri(3), and with a list of queries from
1175 prior calls to nbd_add_meta_context(3) (see nbd_opt_list_meta_con‐
1176 text_queries(3) if you want to supply an explicit query list instead).
1177 This can only be used if nbd_set_opt_mode(3) enabled option mode.
1178 The NBD protocol allows a client to decide how many queries to ask the
1180 server. Rather than taking that list of queries as a parameter to this
1181 function, libnbd reuses the current list of requested meta contexts as
1182 set by nbd_add_meta_context(3); you can use nbd_clear_meta_contexts(3)
1183 to set up a different list of queries. When the list is empty, a server
1184 will typically reply with all contexts that it supports; when the list
1185 is non-empty, the server will reply only with supported contexts that
1186 match the client's request. Note that a reply by the server might be
1187 encoded to represent several feasible contexts within one string,
1188 rather than multiple strings per actual context name that would actu‐
1189 ally succeed during nbd_opt_go(3); so it is still necessary to use
1190 nbd_can_meta_context(3) after connecting to see which contexts are ac‐
1191 tually supported.
1192 The "context" function is called once per server reply, with any
1194 "user_data" passed to this function, and with "name" supplied by the
1195 server. Remember that it is not safe to call nbd_add_meta_context(3)
1196 from within the context of the callback function; rather, your code
1197 must copy any "name" needed for later use after this function com‐
1198 pletes. At present, the return value of the callback is ignored, al‐
1199 though a return of -1 should be avoided.
1200 For convenience, when this function succeeds, it returns the number of
1202 replies returned by the server.
1203 Not all servers understand this request, and even when it is under‐
1205 stood, the server might intentionally send an empty list because it
1206 does not support the requested context, or may encounter a failure af‐
1207 ter delivering partial results. Thus, this function may succeed even
1208 when no contexts are reported, or may fail but have a non-empty list.
1209 Likewise, the NBD protocol does not specify an upper bound for the num‐
1210 ber of replies that might be advertised, so client code should be aware
1211 that a server may send a lengthy list.
1212 val opt_list_meta_context_queries : t -> string list -> (string -> int)
1216 -> int
1217 NBD.opt_list_meta_context_queries t queries context
1220 list available meta contexts, using explicit query list
1222 Request that the server list available meta contexts associated with
1224 the export previously specified by the most recent nbd_set_ex‐
1225 port_name(3) or nbd_connect_uri(3), and with an explicit list of
1226 queries provided as a parameter (see nbd_opt_list_meta_context(3) if
1227 you want to reuse an implicit query list instead). This can only be
1228 used if nbd_set_opt_mode(3) enabled option mode.
1229 The NBD protocol allows a client to decide how many queries to ask the
1231 server. For this function, the list is explicit in the "queries" param‐
1232 eter. When the list is empty, a server will typically reply with all
1233 contexts that it supports; when the list is non-empty, the server will
1234 reply only with supported contexts that match the client's request.
1235 Note that a reply by the server might be encoded to represent several
1236 feasible contexts within one string, rather than multiple strings per
1237 actual context name that would actually succeed during nbd_opt_go(3);
1238 so it is still necessary to use nbd_can_meta_context(3) after connect‐
1239 ing to see which contexts are actually supported.
1240 The "context" function is called once per server reply, with any
1242 "user_data" passed to this function, and with "name" supplied by the
1243 server. Remember that it is not safe to call nbd_add_meta_context(3)
1244 from within the context of the callback function; rather, your code
1245 must copy any "name" needed for later use after this function com‐
1246 pletes. At present, the return value of the callback is ignored, al‐
1247 though a return of -1 should be avoided.
1248 For convenience, when this function succeeds, it returns the number of
1250 replies returned by the server.
1251 Not all servers understand this request, and even when it is under‐
1253 stood, the server might intentionally send an empty list because it
1254 does not support the requested context, or may encounter a failure af‐
1255 ter delivering partial results. Thus, this function may succeed even
1256 when no contexts are reported, or may fail but have a non-empty list.
1257 Likewise, the NBD protocol does not specify an upper bound for the num‐
1258 ber of replies that might be advertised, so client code should be aware
1259 that a server may send a lengthy list.
1260 val opt_set_meta_context : t -> (string -> int) -> int
1264 NBD.opt_set_meta_context t context
1267 select specific meta contexts, using implicit query list
1269 Request that the server supply all recognized meta contexts registered
1271 through prior calls to nbd_add_meta_context(3), in conjunction with the
1272 export previously specified by the most recent nbd_set_export_name(3)
1273 or nbd_connect_uri(3). This can only be used if nbd_set_opt_mode(3) en‐
1274 abled option mode. Normally, this function is redundant, as
1275 nbd_opt_go(3) automatically does the same task if structured replies
1276 have already been negotiated. But manual control over meta context re‐
1277 quests can be useful for fine-grained testing of how a server handles
1278 unusual negotiation sequences. Often, use of this function is coupled
1279 with nbd_set_request_meta_context(3) to bypass the automatic context
1280 request normally performed by nbd_opt_go(3).
1281 The NBD protocol allows a client to decide how many queries to ask the
1283 server. Rather than taking that list of queries as a parameter to this
1284 function, libnbd reuses the current list of requested meta contexts as
1285 set by nbd_add_meta_context(3); you can use nbd_clear_meta_contexts(3)
1286 to set up a different list of queries (see nbd_opt_set_meta_con‐
1287 text_queries(3) to pass an explicit list of contexts instead). Since
1288 this function is primarily designed for testing servers, libnbd does
1289 not prevent the use of this function on an empty list or when
1290 nbd_set_request_structured_replies(3) has disabled structured replies,
1291 in order to see how a server behaves.
1292 The "context" function is called once per server reply, with any
1294 "user_data" passed to this function, and with "name" supplied by the
1295 server. Additionally, each server name will remain visible through
1296 nbd_can_meta_context(3) until the next attempt at nbd_set_ex‐
1297 port_name(3) or nbd_opt_set_meta_context(3), as well as nbd_opt_go(3)
1298 or nbd_opt_info(3) that trigger an automatic meta context request. Re‐
1299 member that it is not safe to call any "nbd_*" APIs from within the
1300 context of the callback function. At present, the return value of the
1301 callback is ignored, although a return of -1 should be avoided.
1302 For convenience, when this function succeeds, it returns the number of
1304 replies returned by the server.
1305 Not all servers understand this request, and even when it is under‐
1307 stood, the server might intentionally send an empty list because it
1308 does not support the requested context, or may encounter a failure af‐
1309 ter delivering partial results. Thus, this function may succeed even
1310 when no contexts are reported, or may fail but have a non-empty list.
1311 val opt_set_meta_context_queries : t -> string list -> (string -> int)
1315 -> int
1316 NBD.opt_set_meta_context_queries t queries context
1319 select specific meta contexts, using explicit query list
1321 Request that the server supply all recognized meta contexts passed in
1323 through "queries", in conjunction with the export previously specified
1324 by the most recent nbd_set_export_name(3) or nbd_connect_uri(3). This
1325 can only be used if nbd_set_opt_mode(3) enabled option mode. Normally,
1326 this function is redundant, as nbd_opt_go(3) automatically does the
1327 same task if structured replies have already been negotiated. But man‐
1328 ual control over meta context requests can be useful for fine-grained
1329 testing of how a server handles unusual negotiation sequences. Often,
1330 use of this function is coupled with nbd_set_request_meta_context(3) to
1331 bypass the automatic context request normally performed by
1332 nbd_opt_go(3).
1333 The NBD protocol allows a client to decide how many queries to ask the
1335 server. This function takes an explicit list of queries; to instead re‐
1336 use an implicit list, see nbd_opt_set_meta_context(3). Since this func‐
1337 tion is primarily designed for testing servers, libnbd does not prevent
1338 the use of this function on an empty list or when nbd_set_re‐
1339 quest_structured_replies(3) has disabled structured replies, in order
1340 to see how a server behaves.
1341 The "context" function is called once per server reply, with any
1343 "user_data" passed to this function, and with "name" supplied by the
1344 server. Additionally, each server name will remain visible through
1345 nbd_can_meta_context(3) until the next attempt at nbd_set_ex‐
1346 port_name(3) or nbd_opt_set_meta_context(3), as well as nbd_opt_go(3)
1347 or nbd_opt_info(3) that trigger an automatic meta context request. Re‐
1348 member that it is not safe to call any "nbd_*" APIs from within the
1349 context of the callback function. At present, the return value of the
1350 callback is ignored, although a return of -1 should be avoided.
1351 For convenience, when this function succeeds, it returns the number of
1353 replies returned by the server.
1354 Not all servers understand this request, and even when it is under‐
1356 stood, the server might intentionally send an empty list because it
1357 does not support the requested context, or may encounter a failure af‐
1358 ter delivering partial results. Thus, this function may succeed even
1359 when no contexts are reported, or may fail but have a non-empty list.
1360 val add_meta_context : t -> string -> unit
1364 NBD.add_meta_context t name
1367 ask server to negotiate metadata context
1369 During connection libnbd can negotiate zero or more metadata contexts
1371 with the server. Metadata contexts are features (such as "base:alloca‐
1372 tion") which describe information returned by the nbd_block_status(3)
1373 command (for "base:allocation" this is whether blocks of data are allo‐
1374 cated, zero or sparse).
1375 This call adds one metadata context to the list to be negotiated. You
1377 can call it as many times as needed. The list is initially empty when
1378 the handle is created; you can check the contents of the list with
1379 nbd_get_nr_meta_contexts(3) and nbd_get_meta_context(3), or clear it
1380 with nbd_clear_meta_contexts(3).
1381 The NBD protocol limits meta context names to 4096 bytes, but servers
1383 may not support the full length. The encoding of meta context names is
1384 always UTF-8.
1385 Not all servers support all metadata contexts. To learn if a context
1387 was actually negotiated, call nbd_can_meta_context(3) after connecting.
1388 The single parameter is the name of the metadata context, for example
1390 "LIBNBD_CONTEXT_BASE_ALLOCATION". <libnbd.h> includes defined con‐
1391 stants beginning with "LIBNBD_CONTEXT_" for some well-known contexts,
1392 but you are free to pass in other contexts.
1393 Other metadata contexts are server-specific, but include
1395 "qemu:dirty-bitmap:..." and "qemu:allocation-depth" for qemu-nbd (see
1396 qemu-nbd *-B* and *-A* options).
1397 val get_nr_meta_contexts : t -> int
1401 NBD.get_nr_meta_contexts t
1404 return the current number of requested meta contexts
1406 During connection libnbd can negotiate zero or more metadata contexts
1408 with the server. Metadata contexts are features (such as "base:alloca‐
1409 tion") which describe information returned by the nbd_block_status(3)
1410 command (for "base:allocation" this is whether blocks of data are allo‐
1411 cated, zero or sparse).
1412 This command returns how many meta contexts have been added to the list
1414 to request from the server via nbd_add_meta_context(3). The server is
1415 not obligated to honor all of the requests; to see what it actually
1416 supports, see nbd_can_meta_context(3).
1417 val get_meta_context : t -> int -> string
1421 NBD.get_meta_context t i
1424 return the i'th meta context request
1426 During connection libnbd can negotiate zero or more metadata contexts
1428 with the server. Metadata contexts are features (such as "base:alloca‐
1429 tion") which describe information returned by the nbd_block_status(3)
1430 command (for "base:allocation" this is whether blocks of data are allo‐
1431 cated, zero or sparse).
1432 This command returns the i'th meta context request, as added by
1434 nbd_add_meta_context(3), and bounded by nbd_get_nr_meta_contexts(3).
1435 val clear_meta_contexts : t -> unit
1439 NBD.clear_meta_contexts t
1442 reset the list of requested meta contexts
1444 During connection libnbd can negotiate zero or more metadata contexts
1446 with the server. Metadata contexts are features (such as "base:alloca‐
1447 tion") which describe information returned by the nbd_block_status(3)
1448 command (for "base:allocation" this is whether blocks of data are allo‐
1449 cated, zero or sparse).
1450 This command resets the list of meta contexts to request back to an
1452 empty list, for re-population by further use of nbd_add_meta_con‐
1453 text(3). It is primarily useful when option negotiation mode is se‐
1454 lected (see nbd_set_opt_mode(3)), for altering the list of attempted
1455 contexts between subsequent export queries.
1456 val set_uri_allow_transports : t -> ALLOW_TRANSPORT.t list -> unit
1460 NBD.set_uri_allow_transports t mask
1463 set the allowed transports in NBD URIs
1465 Set which transports are allowed to appear in NBD URIs. The default is
1467 to allow any transport.
1468 The "mask" parameter may contain any of the following flags ORed to‐
1470 gether:
1471 "LIBNBD_ALLOW_TRANSPORT_TCP" = 0x1 "LIBNBD_ALLOW_TRANSPORT_UNIX" = 0x2
1473 "LIBNBD_ALLOW_TRANSPORT_VSOCK" = 0x4
1474 For convenience, the constant "LIBNBD_ALLOW_TRANSPORT_MASK" is avail‐
1476 able to describe all transports recognized by this build of libnbd. A
1477 future version of the library may add new flags.
1478 val set_uri_allow_tls : t -> TLS.t -> unit
1482 NBD.set_uri_allow_tls t tls
1485 set the allowed TLS settings in NBD URIs
1487 Set which TLS settings are allowed to appear in NBD URIs. The default
1489 is to allow either non-TLS or TLS URIs.
1490 The "tls" parameter can be:
1492 "LIBNBD_TLS_DISABLE" TLS URIs are not permitted, ie. a URI such as
1494 "nbds://..." will be rejected.
1495 "LIBNBD_TLS_ALLOW" This is the default. TLS may be used or not, depend‐
1497 ing on whether the URI uses "nbds" or "nbd".
1498 "LIBNBD_TLS_REQUIRE" TLS URIs are required. All URIs must use "nbds".
1500 val set_uri_allow_local_file : t -> bool -> unit
1504 NBD.set_uri_allow_local_file t allow
1507 set the allowed transports in NBD URIs
1509 Allow NBD URIs to reference local files. This is *disabled* by default.
1511 Currently this setting only controls whether the "tls-psk-file" parame‐
1513 ter in NBD URIs is allowed.
1514 val connect_uri : t -> string -> unit
1518 NBD.connect_uri t uri
1521 connect to NBD URI
1523 Connect (synchronously) to an NBD server and export by specifying the
1525 NBD URI. This call parses the URI and calls nbd_set_export_name(3) and
1526 nbd_set_tls(3) and other calls as needed, followed by nbd_con‐
1527 nect_tcp(3), nbd_connect_unix(3) or nbd_connect_vsock(3).
1528 This call returns when the connection has been made. By default, this
1530 proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can
1531 be used for manual control over option negotiation performed before
1532 transmission phase.
1533 Example URIs supported "nbd://example.com" Connect over TCP, unen‐
1535 crypted, to "example.com" port 10809.
1536 "nbds://example.com" Connect over TCP with TLS, to "example.com" port
1538 10809. If the server does not support TLS then this will fail.
1539 "nbd+unix:///foo?socket=/tmp/nbd.sock" Connect over the Unix domain
1541 socket /tmp/nbd.sock to an NBD server running locally. The export name
1542 is set to "foo" (note without any leading "/" character).
1543 "nbds+unix://alice@/?socket=/tmp/nbd.sock&tls-certificat es=certs" Con‐
1545 nect over a Unix domain socket, enabling TLS and setting the path to a
1546 directory containing certificates and keys.
1547 "nbd+vsock:///" In this scenario libnbd is running in a virtual ma‐
1549 chine. Connect over "AF_VSOCK" to an NBD server running on the hypervi‐
1550 sor.
1551 Supported URI formats The following schemes are supported in the cur‐
1553 rent version of libnbd:
1554 "nbd:" Connect over TCP without using TLS.
1556 "nbds:" Connect over TCP. TLS is required and the connection will fail
1558 if the server does not support TLS.
1559 "nbd+unix:" "nbds+unix:" Connect over a Unix domain socket, without or
1561 with TLS respectively. The "socket" parameter is required.
1562 "nbd+vsock:" "nbds+vsock:" Connect over the "AF_VSOCK" transport, with‐
1564 out or with TLS respectively. You can use nbd_supports_vsock(3) to see
1565 if this build of libnbd supports "AF_VSOCK".
1566 The authority part of the URI (" username@ servername :port ") is
1568 parsed depending on the transport. For TCP it specifies the server to
1569 connect to and optional port number. For "+unix" it should not be
1570 present. For "+vsock" the server name is the numeric CID (eg. 2 to con‐
1571 nect to the host), and the optional port number may be present. If the
1572 "username" is present it is used for TLS authentication.
1573 For all transports, an export name may be present, parsed in accordance
1575 with the NBD URI specification.
1576 Finally the query part of the URI can contain:
1578 socket=SOCKET Specifies the Unix domain socket to connect on. Must be
1580 present for the "+unix" transport and must not be present for the other
1581 transports.
1582 tls-certificates=DIR Set the certificates directory. See
1584 nbd_set_tls_certificates(3). Note this is not allowed by default - see
1585 next section.
1586 tls-psk-file=PSKFILE Set the PSK file. See nbd_set_tls_psk_file(3).
1588 Note this is not allowed by default - see next section.
1589 Disable URI features For security reasons you might want to disable
1591 certain URI features. Pre-filtering URIs is error-prone and should not
1592 be attempted. Instead use the libnbd APIs below to control what can ap‐
1593 pear in URIs. Note you must call these functions on the same handle be‐
1594 fore calling nbd_connect_uri(3) or nbd_aio_connect_uri(3).
1595 TCP, Unix domain socket or "AF_VSOCK" transports Default: all allowed
1597 To select which transports are allowed call nbd_set_uri_allow_trans‐
1599 ports(3).
1600 TLS Default: both non-TLS and TLS connections allowed
1602 To force TLS off or on in URIs call nbd_set_uri_allow_tls(3).
1604 Connect to Unix domain socket in the local filesystem Default: allowed
1606 To prevent this you must disable the "+unix" transport using
1608 nbd_set_uri_allow_transports(3).
1609 Read from local files Default: denied
1611 To allow URIs to contain references to local files (eg. for parameters
1613 like "tls-psk-file") call nbd_set_uri_allow_local_file(3).
1614 Overriding the export name It is possible to override the export name
1616 portion of a URI by using nbd_set_opt_mode(3) to enable option mode,
1617 then using nbd_set_export_name(3) and nbd_opt_go(3) as part of subse‐
1618 quent negotiation.
1619 Optional features This call will fail if libnbd was not compiled with
1621 libxml2; you can test whether this is the case with nbd_sup‐
1622 ports_uri(3).
1623 Support for URIs that require TLS will fail if libnbd was not compiled
1625 with gnutls; you can test whether this is the case with nbd_sup‐
1626 ports_tls(3).
1627 Constructing a URI from an existing connection See nbd_get_uri(3).
1629 val connect_unix : t -> string -> unit
1633 NBD.connect_unix t unixsocket
1636 connect to NBD server over a Unix domain socket
1638 Connect (synchronously) over the named Unix domain socket ("unix‐
1640 socket") to an NBD server running on the same machine.
1641 This call returns when the connection has been made. By default, this
1643 proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can
1644 be used for manual control over option negotiation performed before
1645 transmission phase.
1646 val connect_vsock : t -> int64 -> int64 -> unit
1650 NBD.connect_vsock t cid port
1653 connect to NBD server over AF_VSOCK protocol
1655 Connect (synchronously) over the "AF_VSOCK" protocol from a virtual ma‐
1657 chine to an NBD server, usually running on the host. The "cid" and
1658 "port" parameters specify the server address. Usually "cid" should be 2
1659 (to connect to the host), and "port" might be 10809 or another port
1660 number assigned to you by the host administrator.
1661 Not all systems support "AF_VSOCK"; to determine if libnbd was built on
1663 a system with vsock support, see nbd_supports_vsock(3).
1664 This call returns when the connection has been made. By default, this
1666 proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can
1667 be used for manual control over option negotiation performed before
1668 transmission phase.
1669 val connect_tcp : t -> string -> string -> unit
1673 NBD.connect_tcp t hostname port
1676 connect to NBD server over a TCP port
1678 Connect (synchronously) to the NBD server listening on "hostname:port".
1680 The "port" may be a port name such as "nbd", or it may be a port number
1681 as a string such as "10809".
1682 This call returns when the connection has been made. By default, this
1684 proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can
1685 be used for manual control over option negotiation performed before
1686 transmission phase.
1687 val connect_socket : t -> Unix.file_descr -> unit
1691 NBD.connect_socket t sock
1694 connect directly to a connected socket
1696 Pass a connected socket "sock" through which libnbd will talk to the
1698 NBD server.
1699 The caller is responsible for creating and connecting this socket by
1701 some method, before passing it to libnbd.
1702 If this call returns without error then socket ownership is passed to
1704 libnbd. Libnbd will close the socket when the handle is closed. The
1705 caller must not use the socket in any way.
1706 This call returns when the connection has been made. By default, this
1708 proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can
1709 be used for manual control over option negotiation performed before
1710 transmission phase.
1711 val connect_command : t -> string list -> unit
1715 NBD.connect_command t argv
1718 connect to NBD server command
1720 Run the command as a subprocess and connect to it over stdin/stdout.
1722 This is for use with NBD servers which can behave like inetd clients,
1723 such as nbdkit(1) using the *-s*/*--single* flag, and nbd-server(1)
1724 with port number set to 0.
1725 To run qemu-nbd(1), use nbd_connect_systemd_socket_activation(3) in‐
1727 stead.
1728 Subprocess Libnbd will fork the "argv" command and pass the NBD socket
1730 to it using file descriptors 0 and 1 (stdin/stdout):
1731 ┌─────────┬─────────┐ ┌────────────────┐ │ program │ libnbd │ │
1733 NBD server │ │ │ │ │ (argv) │ │ │
1734 socket ╍╍╍╍╍╍╍╍▶ stdin/stdout │ └─────────┴─────────┘
1735 └────────────────┘
1736 When the NBD handle is closed the server subprocess is killed.
1738 This call returns when the connection has been made. By default, this
1740 proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can
1741 be used for manual control over option negotiation performed before
1742 transmission phase.
1743 val connect_systemd_socket_activation : t -> string list -> unit
1747 NBD.connect_systemd_socket_activation t argv
1750 connect using systemd socket activation
1752 Run the command as a subprocess and connect to it using systemd socket
1754 activation.
1755 This is especially useful for running qemu-nbd(1) as a subprocess of
1757 libnbd, for example to use it to open qcow2 files.
1758 To run nbdkit as a subprocess, this function can be used, or nbd_con‐
1760 nect_command(3).
1761 To run nbd-server(1) as a subprocess, this function cannot be used, you
1763 must use nbd_connect_command(3).
1764 Socket activation Libnbd will fork the "argv" command and pass an NBD
1766 socket to it using special "LISTEN_*" environment variables (as defined
1767 by the systemd socket activation protocol).
1768 ┌─────────┬─────────┐ ┌───────────────┐ │ program │ libnbd │ │
1770 qemu-nbd or │ │ │ │ │ other server │ │ │
1771 socket ╍╍╍╍╍╍╍╍▶ │ └─────────┴─────────┘
1772 └───────────────┘
1773 When the NBD handle is closed the server subprocess is killed.
1775 Socket name The socket activation protocol lets you optionally give the
1777 socket a name. If used, the name is passed to the NBD server using the
1778 "LISTEN_FDNAMES" environment variable. To provide a socket name, call
1779 nbd_set_socket_activation_name(3) before calling the connect function.
1780 This call returns when the connection has been made. By default, this
1782 proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can
1783 be used for manual control over option negotiation performed before
1784 transmission phase.
1785 val set_socket_activation_name : t -> string -> unit
1789 NBD.set_socket_activation_name t socket_name
1792 set the socket activation name
1794 When running an NBD server using nbd_connect_systemd_socket_activa‐
1796 tion(3) you can optionally name the socket. Call this function before
1797 connecting to the server.
1798 Some servers such as qemu-storage-daemon(1) can use this information to
1800 associate the socket with a name used on the command line, but most
1801 servers will ignore it. The name is passed through the "LISTEN_FDNAMES"
1802 environment variable.
1803 The parameter "socket_name" can be a short alphanumeric string. If it
1805 is set to the empty string (also the default when the handle is cre‐
1806 ated) then the name "unknown" will be seen by the server.
1807 val get_socket_activation_name : t -> string
1811 NBD.get_socket_activation_name t
1814 get the socket activation name
1816 Return the socket name used when you call nbd_connect_sys‐
1818 temd_socket_activation(3) on the same handle. By default this will re‐
1819 turn the empty string meaning that the server will see the name "un‐
1820 known".
1821 val is_read_only : t -> bool
1825 NBD.is_read_only t
1828 is the NBD export read-only?
1830 Returns true if the NBD export is read-only; writes and write-like op‐
1832 erations will fail.
1833 This call does not block, because it returns data that is saved in the
1835 handle from the NBD protocol handshake.
1836 val can_flush : t -> bool
1840 NBD.can_flush t
1843 does the server support the flush command?
1845 Returns true if the server supports the flush command (see
1847 nbd_flush(3), nbd_aio_flush(3)). Returns false if the server does not.
1848 This call does not block, because it returns data that is saved in the
1850 handle from the NBD protocol handshake.
1851 val can_fua : t -> bool
1855 NBD.can_fua t
1858 does the server support the FUA flag?
1860 Returns true if the server supports the FUA flag on certain commands
1862 (see nbd_pwrite(3)).
1863 This call does not block, because it returns data that is saved in the
1865 handle from the NBD protocol handshake.
1866 val is_rotational : t -> bool
1870 NBD.is_rotational t
1873 is the NBD disk rotational (like a disk)?
1875 Returns true if the disk exposed over NBD is rotational (like a tradi‐
1877 tional floppy or hard disk). Returns false if the disk has no penalty
1878 for random access (like an SSD or RAM disk).
1879 This call does not block, because it returns data that is saved in the
1881 handle from the NBD protocol handshake.
1882 val can_trim : t -> bool
1886 NBD.can_trim t
1889 does the server support the trim command?
1891 Returns true if the server supports the trim command (see nbd_trim(3),
1893 nbd_aio_trim(3)). Returns false if the server does not.
1894 This call does not block, because it returns data that is saved in the
1896 handle from the NBD protocol handshake.
1897 val can_zero : t -> bool
1901 NBD.can_zero t
1904 does the server support the zero command?
1906 Returns true if the server supports the zero command (see nbd_zero(3),
1908 nbd_aio_zero(3)). Returns false if the server does not.
1909 This call does not block, because it returns data that is saved in the
1911 handle from the NBD protocol handshake.
1912 val can_fast_zero : t -> bool
1916 NBD.can_fast_zero t
1919 does the server support the fast zero flag?
1921 Returns true if the server supports the use of the
1923 "LIBNBD_CMD_FLAG_FAST_ZERO" flag to the zero command (see nbd_zero(3),
1924 nbd_aio_zero(3)). Returns false if the server does not.
1925 This call does not block, because it returns data that is saved in the
1927 handle from the NBD protocol handshake.
1928 val can_df : t -> bool
1932 NBD.can_df t
1935 does the server support the don't fragment flag to pread?
1937 Returns true if the server supports structured reads with an ability to
1939 request a non-fragmented read (see nbd_pread_structured(3),
1940 nbd_aio_pread_structured(3)). Returns false if the server either lacks
1941 structured reads or if it does not support a non-fragmented read re‐
1942 quest.
1943 This call does not block, because it returns data that is saved in the
1945 handle from the NBD protocol handshake.
1946 val can_multi_conn : t -> bool
1950 NBD.can_multi_conn t
1953 does the server support multi-conn?
1955 Returns true if the server supports multi-conn. Returns false if the
1957 server does not.
1958 It is not safe to open multiple handles connecting to the same server
1960 if you will write to the server and the server does not advertise
1961 multi-conn support. The safe way to check for this is to open one con‐
1962 nection, check this flag is true, then open further connections as re‐
1963 quired.
1964 This call does not block, because it returns data that is saved in the
1966 handle from the NBD protocol handshake.
1967 val can_cache : t -> bool
1971 NBD.can_cache t
1974 does the server support the cache command?
1976 Returns true if the server supports the cache command (see
1978 nbd_cache(3), nbd_aio_cache(3)). Returns false if the server does not.
1979 This call does not block, because it returns data that is saved in the
1981 handle from the NBD protocol handshake.
1982 val can_meta_context : t -> string -> bool
1986 NBD.can_meta_context t metacontext
1989 does the server support a specific meta context?
1991 Returns true if the server supports the given meta context (see
1993 nbd_add_meta_context(3)). Returns false if the server does not. It is
1994 possible for this command to fail if meta contexts were requested but
1995 there is a missing or failed attempt at NBD_OPT_SET_META_CONTEXT during
1996 option negotiation.
1997 The single parameter is the name of the metadata context, for example
1999 "LIBNBD_CONTEXT_BASE_ALLOCATION". <libnbd.h> includes defined con‐
2000 stants for well-known namespace contexts beginning with "LIBNBD_CON‐
2001 TEXT_", but you are free to pass in other contexts.
2002 This call does not block, because it returns data that is saved in the
2004 handle from the NBD protocol handshake.
2005 val get_protocol : t -> string
2009 NBD.get_protocol t
2012 return the NBD protocol variant
2014 Return the NBD protocol variant in use on the connection. At the moment
2016 this returns one of the strings "oldstyle", "newstyle" or "new‐
2017 style-fixed". Other strings might be returned in the future. Most mod‐
2018 ern NBD servers use "newstyle-fixed".
2019 This call does not block, because it returns data that is saved in the
2021 handle from the NBD protocol handshake.
2022 val get_size : t -> int64
2026 NBD.get_size t
2029 return the export size
2031 Returns the size in bytes of the NBD export.
2033 Note that this call fails with "EOVERFLOW" for an unlikely server that
2035 advertises a size which cannot fit in a 64-bit signed integer.
2036 This call does not block, because it returns data that is saved in the
2038 handle from the NBD protocol handshake.
2039 val get_block_size : t -> SIZE.t -> int64
2043 NBD.get_block_size t size_type
2046 return a specific server block size constraint
2048 Returns a specific size constraint advertised by the server, if any. If
2050 the return is zero, the server did not advertise a constraint.
2051 "size_type" must be one of the following constraints:
2052 "LIBNBD_SIZE_MINIMUM" = 0 If non-zero, this will be a power of 2 be‐
2054 tween 1 and 64k; any client request that is not aligned in length or
2055 offset to this size is likely to fail with "EINVAL". The image size
2056 will generally also be a multiple of this value (if not, the final few
2057 bytes are inaccessible while obeying alignment constraints). If zero,
2058 it is safest to assume a minimum block size of 512, although many
2059 servers support a minimum block size of 1. If the server provides a
2060 constraint, then libnbd defaults to honoring that constraint
2061 client-side unless "LIBNBD_STRICT_ALIGN" is cleared in
2062 nbd_set_strict_mode(3).
2063 "LIBNBD_SIZE_PREFERRED" = 1 If non-zero, this is a power of 2 repre‐
2065 senting the preferred size for efficient I/O. Smaller requests may in‐
2066 cur overhead such as read-modify-write cycles that will not be present
2067 when using I/O that is a multiple of this value. This value may be
2068 larger than the size of the export. If zero, using 4k as a preferred
2069 block size tends to give decent performance.
2070 "LIBNBD_SIZE_MAXIMUM" = 2 If non-zero, this represents the maximum
2072 length that the server is willing to handle during nbd_pread(3) or
2073 nbd_pwrite(3). Other functions like nbd_zero(3) may still be able to
2074 use larger sizes. Note that this function returns what the server ad‐
2075 vertised, but libnbd itself imposes a maximum of 64M. If zero, some NBD
2076 servers will abruptly disconnect if a transaction involves more than
2077 32M.
2078 "LIBNBD_SIZE_PAYLOAD" = 3 This value is not advertised by the server,
2080 but rather represents the maximum outgoing payload size for a given
2081 connection that libnbd will enforce unless "LIBNBD_STRICT_PAYLOAD" is
2082 cleared in nbd_set_strict_mode(3). It is always non-zero: never smaller
2083 than 1M, never larger than 64M, and matches "LIBNBD_SIZE_MAXIMUM" when
2084 possible.
2085 Future NBD extensions may result in additional "size_type" values. Note
2087 that by default, libnbd requests all available block sizes, but that a
2088 server may differ in what sizes it chooses to report if nbd_set_re‐
2089 quest_block_size(3) alters whether the client requests sizes.
2090 This call does not block, because it returns data that is saved in the
2092 handle from the NBD protocol handshake.
2093 val pread : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 -> unit
2097 NBD.pread t ?flags buf offset
2100 read from the NBD server
2102 Issue a read command to the NBD server for the range starting at "off‐
2104 set" and ending at "offset" + "count" - 1. NBD can only read all or
2105 nothing using this call. The call returns when the data has been read
2106 fully into "buf" or there is an error. See also nbd_pread_struc‐
2107 tured(3), if finer visibility is required into the server's replies, or
2108 if you want to use "LIBNBD_CMD_FLAG_DF".
2109 Note that libnbd currently enforces a maximum read buffer of 64MiB,
2111 even if the server would permit a larger buffer in a single transac‐
2112 tion; attempts to exceed this will result in an "ERANGE" error. The
2113 server may enforce a smaller limit, which can be learned with
2114 nbd_get_block_size(3).
2115 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
2117 tocol extensions).
2118 Note that if this command fails, and nbd_get_pread_initialize(3) re‐
2120 turns true, then libnbd sanitized "buf", but it is unspecified whether
2121 the contents of "buf" will read as zero or as partial results from the
2122 server. If nbd_get_pread_initialize(3) returns false, then libnbd did
2123 not sanitize "buf", and the contents are undefined on failure.
2124 By default, libnbd will reject attempts to use this function with pa‐
2126 rameters that are likely to result in server failure, such as request‐
2127 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2128 used to alter which scenarios should await a server reply rather than
2129 failing fast.
2130 val pread_structured : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 ->
2134 (bytes -> int64 -> int -> int Stdlib.ref -> int) -> unit
2135 NBD.pread_structured t ?flags buf offset chunk
2138 read from the NBD server
2140 Issue a read command to the NBD server for the range starting at "off‐
2142 set" and ending at "offset" + "count" - 1. The server's response may be
2143 subdivided into chunks which may arrive out of order before reassembly
2144 into the original buffer; the "chunk" callback is used for notification
2145 after each chunk arrives, and may perform additional sanity checking on
2146 the server's reply. The callback cannot call "nbd_*" APIs on the same
2147 handle since it holds the handle lock and will cause a deadlock. If the
2148 callback returns -1, and no earlier error has been detected, then the
2149 overall read command will fail with any non-zero value stored into the
2150 callback's "error" parameter (with a default of "EPROTO"); but any fur‐
2151 ther chunks will still invoke the callback.
2152 The "chunk" function is called once per chunk of data received, with
2154 the "user_data" passed to this function. The "subbuf" and "count" pa‐
2155 rameters represent the subset of the original buffer which has just
2156 been populated by results from the server (in C, "subbuf" always points
2157 within the original "buf"; but this guarantee may not extend to other
2158 language bindings). The "offset" parameter represents the absolute off‐
2159 set at which "subbuf" begins within the image (note that this is not
2160 the relative offset of "subbuf" within the original buffer "buf").
2161 Changes to "error" on output are ignored unless the callback fails. The
2162 input meaning of the "error" parameter is controlled by the "status"
2163 parameter, which is one of
2164 "LIBNBD_READ_DATA" = 1 "subbuf" was populated with "count" bytes of
2166 data. On input, "error" contains the errno value of any earlier de‐
2167 tected error, or zero.
2168 "LIBNBD_READ_HOLE" = 2 "subbuf" represents a hole, and contains "count"
2170 NUL bytes. On input, "error" contains the errno value of any earlier
2171 detected error, or zero.
2172 "LIBNBD_READ_ERROR" = 3 "count" is 0, so "subbuf" is unusable. On in‐
2174 put, "error" contains the errno value reported by the server as occur‐
2175 ring while reading that "offset", regardless if any earlier error has
2176 been detected.
2177 Future NBD extensions may permit other values for "status", but those
2179 will not be returned to a client that has not opted in to requesting
2180 such extensions. If the server is non-compliant, it is possible for the
2181 "chunk" function to be called more times than you expect or with
2182 "count" 0 for "LIBNBD_READ_DATA" or "LIBNBD_READ_HOLE". It is also pos‐
2183 sible that the "chunk" function is not called at all (in particular,
2184 "LIBNBD_READ_ERROR" is used only when an error is associated with a
2185 particular offset, and not when the server reports a generic error),
2186 but you are guaranteed that the callback was called at least once if
2187 the overall read succeeds. Libnbd does not validate that the server
2188 obeyed the requirement that a read call must not have overlapping
2189 chunks and must not succeed without enough chunks to cover the entire
2190 request.
2191 Note that libnbd currently enforces a maximum read buffer of 64MiB,
2193 even if the server would permit a larger buffer in a single transac‐
2194 tion; attempts to exceed this will result in an "ERANGE" error. The
2195 server may enforce a smaller limit, which can be learned with
2196 nbd_get_block_size(3).
2197 The "flags" parameter may be 0 for no flags, or may contain
2199 "LIBNBD_CMD_FLAG_DF" meaning that the server should not reply with more
2200 than one fragment (if that is supported - some servers cannot do this,
2201 see nbd_can_df(3)). Libnbd does not validate that the server actually
2202 obeys the flag.
2203 Note that if this command fails, and nbd_get_pread_initialize(3) re‐
2205 turns true, then libnbd sanitized "buf", but it is unspecified whether
2206 the contents of "buf" will read as zero or as partial results from the
2207 server. If nbd_get_pread_initialize(3) returns false, then libnbd did
2208 not sanitize "buf", and the contents are undefined on failure.
2209 By default, libnbd will reject attempts to use this function with pa‐
2211 rameters that are likely to result in server failure, such as request‐
2212 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2213 used to alter which scenarios should await a server reply rather than
2214 failing fast.
2215 val pwrite : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 -> unit
2219 NBD.pwrite t ?flags buf offset
2222 write to the NBD server
2224 Issue a write command to the NBD server, writing the data in "buf" to
2226 the range starting at "offset" and ending at "offset" + "count" - 1.
2227 NBD can only write all or nothing using this call. The call returns
2228 when the command has been acknowledged by the server, or there is an
2229 error. Note this will generally return an error if nbd_is_read_only(3)
2230 is true.
2231 Note that libnbd defaults to enforcing a maximum write buffer of the
2233 lesser of 64MiB or any maximum payload size advertised by the server;
2234 attempts to exceed this will generally result in a client-side "ERANGE"
2235 error, rather than a server-side disconnection. The actual limit can be
2236 learned with nbd_get_block_size(3).
2237 The "flags" parameter may be 0 for no flags, or may contain
2239 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
2240 the data has been committed to permanent storage (if that is supported
2241 - some servers cannot do this, see nbd_can_fua(3)).
2242 By default, libnbd will reject attempts to use this function with pa‐
2244 rameters that are likely to result in server failure, such as request‐
2245 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2246 used to alter which scenarios should await a server reply rather than
2247 failing fast.
2248 val shutdown : ?flags:SHUTDOWN.t list -> t -> unit
2252 NBD.shutdown t ?flags
2255 disconnect from the NBD server
2257 Issue the disconnect command to the NBD server. This is a nice way to
2259 tell the server we are going away, but from the client's point of view
2260 has no advantage over abruptly closing the connection (see
2261 nbd_close(3)).
2262 This function works whether or not the handle is ready for transmission
2264 of commands. If more fine-grained control is needed, see nbd_aio_dis‐
2265 connect(3).
2266 The "flags" argument is a bitmask, including zero or more of the fol‐
2268 lowing shutdown flags:
2269 "LIBNBD_SHUTDOWN_ABANDON_PENDING" = 0x10000 If there are any pending
2271 requests which have not yet been sent to the server (see
2272 nbd_aio_in_flight(3)), abandon them without sending them to the server,
2273 rather than the usual practice of issuing those commands before inform‐
2274 ing the server of the intent to disconnect.
2275 For convenience, the constant "LIBNBD_SHUTDOWN_MASK" is available to
2277 describe all shutdown flags recognized by this build of libnbd. A fu‐
2278 ture version of the library may add new flags.
2279 val flush : ?flags:CMD_FLAG.t list -> t -> unit
2283 NBD.flush t ?flags
2286 send flush command to the NBD server
2288 Issue the flush command to the NBD server. The function should return
2290 when all write commands which have completed have been committed to
2291 permanent storage on the server. Note this will generally return an er‐
2292 ror if nbd_can_flush(3) is false.
2293 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
2295 tocol extensions).
2296 By default, libnbd will reject attempts to use this function with pa‐
2298 rameters that are likely to result in server failure, such as request‐
2299 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2300 used to alter which scenarios should await a server reply rather than
2301 failing fast.
2302 val trim : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
2306 NBD.trim t ?flags count offset
2309 send trim command to the NBD server
2311 Issue a trim command to the NBD server, which if supported by the
2313 server causes a hole to be punched in the backing store starting at
2314 "offset" and ending at "offset" + "count" - 1. The call returns when
2315 the command has been acknowledged by the server, or there is an error.
2316 Note this will generally return an error if nbd_can_trim(3) is false or
2317 nbd_is_read_only(3) is true.
2318 Note that not all servers can support a "count" of 4GiB or larger. The
2320 NBD protocol does not yet have a way for a client to learn if the
2321 server will enforce an even smaller maximum trim size, although a fu‐
2322 ture extension may add a constraint visible in nbd_get_block_size(3).
2323 The "flags" parameter may be 0 for no flags, or may contain
2325 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
2326 the data has been committed to permanent storage (if that is supported
2327 - some servers cannot do this, see nbd_can_fua(3)).
2328 By default, libnbd will reject attempts to use this function with pa‐
2330 rameters that are likely to result in server failure, such as request‐
2331 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2332 used to alter which scenarios should await a server reply rather than
2333 failing fast.
2334 val cache : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
2338 NBD.cache t ?flags count offset
2341 send cache (prefetch) command to the NBD server
2343 Issue the cache (prefetch) command to the NBD server, which if sup‐
2345 ported by the server causes data to be prefetched into faster storage
2346 by the server, speeding up a subsequent nbd_pread(3) call. The server
2347 can also silently ignore this command. Note this will generally return
2348 an error if nbd_can_cache(3) is false.
2349 Note that not all servers can support a "count" of 4GiB or larger. The
2351 NBD protocol does not yet have a way for a client to learn if the
2352 server will enforce an even smaller maximum cache size, although a fu‐
2353 ture extension may add a constraint visible in nbd_get_block_size(3).
2354 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
2356 tocol extensions).
2357 By default, libnbd will reject attempts to use this function with pa‐
2359 rameters that are likely to result in server failure, such as request‐
2360 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2361 used to alter which scenarios should await a server reply rather than
2362 failing fast.
2363 val zero : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
2367 NBD.zero t ?flags count offset
2370 send write zeroes command to the NBD server
2372 Issue a write zeroes command to the NBD server, which if supported by
2374 the server causes a zeroes to be written efficiently starting at "off‐
2375 set" and ending at "offset"
2376 -"count" - 1. The call returns when the command has been acknowledged
2378 by the server, or there is an error. Note this will generally return
2379 an error if nbd_can_zero(3) is false or nbd_is_read_only(3) is true.
2380 Note that not all servers can support a "count" of 4GiB or larger. The
2382 NBD protocol does not yet have a way for a client to learn if the
2383 server will enforce an even smaller maximum zero size, although a fu‐
2384 ture extension may add a constraint visible in nbd_get_block_size(3).
2385 Also, some servers may permit a larger zero request only when the
2386 "LIBNBD_CMD_FLAG_FAST_ZERO" is in use.
2387 The "flags" parameter may be 0 for no flags, or may contain
2389 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
2390 the data has been committed to permanent storage (if that is supported
2391 - some servers cannot do this, see nbd_can_fua(3)),
2392 "LIBNBD_CMD_FLAG_NO_HOLE" meaning that the server should favor writing
2393 actual allocated zeroes over punching a hole, and/or
2394 "LIBNBD_CMD_FLAG_FAST_ZERO" meaning that the server must fail quickly
2395 if writing zeroes is no faster than a normal write (if that is sup‐
2396 ported - some servers cannot do this, see nbd_can_fast_zero(3)).
2397 By default, libnbd will reject attempts to use this function with pa‐
2399 rameters that are likely to result in server failure, such as request‐
2400 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2401 used to alter which scenarios should await a server reply rather than
2402 failing fast.
2403 val block_status : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 ->
2407 (string -> int64 -> int64 array -> int Stdlib.ref -> int) -> unit
2408 NBD.block_status t ?flags count offset extent
2411 send block status command to the NBD server
2413 Issue the block status command to the NBD server. If supported by the
2415 server, this causes metadata context information about blocks beginning
2416 from the specified offset to be returned. The "count" parameter is a
2417 hint: the server may choose to return less status, or the final block
2418 may extend beyond the requested range. If multiple contexts are sup‐
2419 ported, the number of blocks and cumulative length of those blocks need
2420 not be identical between contexts.
2421 Note that not all servers can support a "count" of 4GiB or larger. The
2423 NBD protocol does not yet have a way for a client to learn if the
2424 server will enforce an even smaller maximum block status size, although
2425 a future extension may add a constraint visible in
2426 nbd_get_block_size(3).
2427 Depending on which metadata contexts were enabled before connecting
2429 (see nbd_add_meta_context(3)) and which are supported by the server
2430 (see nbd_can_meta_context(3)) this call returns information about ex‐
2431 tents by calling back to the "extent" function. The callback cannot
2432 call "nbd_*" APIs on the same handle since it holds the handle lock and
2433 will cause a deadlock. If the callback returns -1, and no earlier error
2434 has been detected, then the overall block status command will fail with
2435 any non-zero value stored into the callback's "error" parameter (with a
2436 default of "EPROTO"); but any further contexts will still invoke the
2437 callback.
2438 The "extent" function is called once per type of metadata available,
2440 with the "user_data" passed to this function. The "metacontext" parame‐
2441 ter is a string such as "base:allocation". The "entries" array is an
2442 array of pairs of integers with the first entry in each pair being the
2443 length (in bytes) of the block and the second entry being a sta‐
2444 tus/flags field which is specific to the metadata context. (The number
2445 of pairs passed to the function is "nr_entries/2".) The NBD protocol
2446 document in the section about "NBD_REPLY_TYPE_BLOCK_STATUS" describes
2447 the meaning of this array; for contexts known to libnbd, <libnbd.h>
2448 contains constants beginning with "LIBNBD_STATE_" that may help deci‐
2449 pher the values. On entry to the callback, the "error" parameter con‐
2450 tains the errno value of any previously detected error, but even if an
2451 earlier error was detected, the current "metacontext" and "entries" are
2452 valid.
2453 It is possible for the extent function to be called more times than you
2455 expect (if the server is buggy), so always check the "metacontext"
2456 field to ensure you are receiving the data you expect. It is also pos‐
2457 sible that the extent function is not called at all, even for metadata
2458 contexts that you requested. This indicates either that the server
2459 doesn't support the context or for some other reason cannot return the
2460 data.
2461 The "flags" parameter may be 0 for no flags, or may contain
2463 "LIBNBD_CMD_FLAG_REQ_ONE" meaning that the server should return only
2464 one extent per metadata context where that extent does not exceed
2465 "count" bytes; however, libnbd does not validate that the server obeyed
2466 the flag.
2467 By default, libnbd will reject attempts to use this function with pa‐
2469 rameters that are likely to result in server failure, such as request‐
2470 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2471 used to alter which scenarios should await a server reply rather than
2472 failing fast.
2473 val poll : t -> int -> int
2477 NBD.poll t timeout
2480 poll the handle once
2482 This is a simple implementation of poll(2) which is used internally by
2484 synchronous API calls. On success, it returns 0 if the "timeout" (in
2485 milliseconds) occurs, or 1 if the poll completed and the state machine
2486 progressed. Set "timeout" to -1 to block indefinitely (but be careful
2487 that eventual action is actually expected - for example, if the connec‐
2488 tion is established but there are no commands in flight, using an infi‐
2489 nite timeout will permanently block).
2490 This function is mainly useful as an example of how you might integrate
2492 libnbd with your own main loop, rather than being intended as something
2493 you would use.
2494 val poll2 : t -> Unix.file_descr -> int -> int
2498 NBD.poll2 t fd timeout
2501 poll the handle once, with fd
2503 This is the same as nbd_poll(3), but an additional file descriptor pa‐
2505 rameter is passed. The additional fd is also polled (using "POLLIN").
2506 One use for this is to wait for an eventfd(2).
2507 val aio_connect : t -> Unix.sockaddr -> unit
2511 NBD.aio_connect t addr
2514 connect to the NBD server
2516 Begin connecting to the NBD server. The "addr" and "addrlen" parameters
2518 specify the address of the socket to connect to.
2519 You can check if the connection attempt is still underway by calling
2521 nbd_aio_is_connecting(3). If nbd_set_opt_mode(3) is enabled, the con‐
2522 nection is ready for manual option negotiation once nbd_aio_is_negoti‐
2523 ating(3) returns true; otherwise, the connection attempt will include
2524 the NBD handshake, and is ready for use once nbd_aio_is_ready(3) re‐
2525 turns true.
2526 val aio_connect_uri : t -> string -> unit
2530 NBD.aio_connect_uri t uri
2533 connect to an NBD URI
2535 Begin connecting to the NBD URI "uri". Parameters behave as documented
2537 in nbd_connect_uri(3).
2538 You can check if the connection attempt is still underway by calling
2540 nbd_aio_is_connecting(3). If nbd_set_opt_mode(3) is enabled, the con‐
2541 nection is ready for manual option negotiation once nbd_aio_is_negoti‐
2542 ating(3) returns true; otherwise, the connection attempt will include
2543 the NBD handshake, and is ready for use once nbd_aio_is_ready(3) re‐
2544 turns true.
2545 val aio_connect_unix : t -> string -> unit
2549 NBD.aio_connect_unix t unixsocket
2552 connect to the NBD server over a Unix domain socket
2554 Begin connecting to the NBD server over Unix domain socket ("unix‐
2556 socket"). Parameters behave as documented in nbd_connect_unix(3).
2557 You can check if the connection attempt is still underway by calling
2559 nbd_aio_is_connecting(3). If nbd_set_opt_mode(3) is enabled, the con‐
2560 nection is ready for manual option negotiation once nbd_aio_is_negoti‐
2561 ating(3) returns true; otherwise, the connection attempt will include
2562 the NBD handshake, and is ready for use once nbd_aio_is_ready(3) re‐
2563 turns true.
2564 val aio_connect_vsock : t -> int64 -> int64 -> unit
2568 NBD.aio_connect_vsock t cid port
2571 connect to the NBD server over AF_VSOCK socket
2573 Begin connecting to the NBD server over the "AF_VSOCK" protocol to the
2575 server "cid:port". Parameters behave as documented in nbd_con‐
2576 nect_vsock(3).
2577 You can check if the connection attempt is still underway by calling
2579 nbd_aio_is_connecting(3). If nbd_set_opt_mode(3) is enabled, the con‐
2580 nection is ready for manual option negotiation once nbd_aio_is_negoti‐
2581 ating(3) returns true; otherwise, the connection attempt will include
2582 the NBD handshake, and is ready for use once nbd_aio_is_ready(3) re‐
2583 turns true.
2584 val aio_connect_tcp : t -> string -> string -> unit
2588 NBD.aio_connect_tcp t hostname port
2591 connect to the NBD server over a TCP port
2593 Begin connecting to the NBD server listening on "hostname:port". Param‐
2595 eters behave as documented in nbd_connect_tcp(3).
2596 You can check if the connection attempt is still underway by calling
2598 nbd_aio_is_connecting(3). If nbd_set_opt_mode(3) is enabled, the con‐
2599 nection is ready for manual option negotiation once nbd_aio_is_negoti‐
2600 ating(3) returns true; otherwise, the connection attempt will include
2601 the NBD handshake, and is ready for use once nbd_aio_is_ready(3) re‐
2602 turns true.
2603 val aio_connect_socket : t -> Unix.file_descr -> unit
2607 NBD.aio_connect_socket t sock
2610 connect directly to a connected socket
2612 Begin connecting to the connected socket "fd". Parameters behave as
2614 documented in nbd_connect_socket(3).
2615 You can check if the connection attempt is still underway by calling
2617 nbd_aio_is_connecting(3). If nbd_set_opt_mode(3) is enabled, the con‐
2618 nection is ready for manual option negotiation once nbd_aio_is_negoti‐
2619 ating(3) returns true; otherwise, the connection attempt will include
2620 the NBD handshake, and is ready for use once nbd_aio_is_ready(3) re‐
2621 turns true.
2622 val aio_connect_command : t -> string list -> unit
2626 NBD.aio_connect_command t argv
2629 connect to the NBD server
2631 Run the command as a subprocess and begin connecting to it over
2633 stdin/stdout. Parameters behave as documented in nbd_connect_com‐
2634 mand(3).
2635 You can check if the connection attempt is still underway by calling
2637 nbd_aio_is_connecting(3). If nbd_set_opt_mode(3) is enabled, the con‐
2638 nection is ready for manual option negotiation once nbd_aio_is_negoti‐
2639 ating(3) returns true; otherwise, the connection attempt will include
2640 the NBD handshake, and is ready for use once nbd_aio_is_ready(3) re‐
2641 turns true.
2642 val aio_connect_systemd_socket_activation : t -> string list -> unit
2646 NBD.aio_connect_systemd_socket_activation t argv
2649 connect using systemd socket activation
2651 Run the command as a subprocess and begin connecting to it using sys‐
2653 temd socket activation. Parameters behave as documented in nbd_con‐
2654 nect_systemd_socket_activation(3).
2655 You can check if the connection attempt is still underway by calling
2657 nbd_aio_is_connecting(3). If nbd_set_opt_mode(3) is enabled, the con‐
2658 nection is ready for manual option negotiation once nbd_aio_is_negoti‐
2659 ating(3) returns true; otherwise, the connection attempt will include
2660 the NBD handshake, and is ready for use once nbd_aio_is_ready(3) re‐
2661 turns true.
2662 val aio_opt_go : ?completion:(int Stdlib.ref -> int) -> t -> unit
2666 NBD.aio_opt_go t ?completion
2669 end negotiation and move on to using an export
2671 Request that the server finish negotiation and move on to serving the
2673 export previously specified by the most recent nbd_set_export_name(3)
2674 or nbd_connect_uri(3). This can only be used if nbd_set_opt_mode(3)
2675 enabled option mode.
2676 To determine when the request completes, wait for nbd_aio_is_connect‐
2678 ing(3) to return false. Or supply the optional "completion_callback"
2679 which will be invoked as described in "Completion callbacks" in
2680 libnbd(3), except that it is automatically retired regardless of return
2681 value. Note that directly detecting whether the server returns an error
2682 (as is done by the return value of the synchronous counterpart) is only
2683 possible with a completion callback; however it is also possible to in‐
2684 directly detect an error when nbd_aio_is_negotiating(3) returns true.
2685 val aio_opt_abort : t -> unit
2689 NBD.aio_opt_abort t
2692 end negotiation and close the connection
2694 Request that the server finish negotiation, gracefully if possible,
2696 then close the connection. This can only be used if nbd_set_opt_mode(3)
2697 enabled option mode.
2698 To determine when the request completes, wait for nbd_aio_is_connect‐
2700 ing(3) to return false.
2701 val aio_opt_starttls : ?completion:(int Stdlib.ref -> int) -> t -> unit
2705 NBD.aio_opt_starttls t ?completion
2708 request the server to initiate TLS
2710 Request that the server initiate a secure TLS connection, by sending
2712 "NBD_OPT_STARTTLS". This behaves like the synchronous counterpart
2713 nbd_opt_starttls(3), except that it does not wait for the server's re‐
2714 sponse.
2715 To determine when the request completes, wait for nbd_aio_is_connect‐
2717 ing(3) to return false. Or supply the optional "completion_callback"
2718 which will be invoked as described in "Completion callbacks" in
2719 libnbd(3), except that it is automatically retired regardless of return
2720 value. Note that detecting whether the server returns an error (as is
2721 done by the return value of the synchronous counterpart) is only possi‐
2722 ble with a completion callback.
2723 val aio_opt_structured_reply : ?completion:(int Stdlib.ref -> int) -> t
2727 -> unit
2728 NBD.aio_opt_structured_reply t ?completion
2731 request the server to enable structured replies
2733 Request that the server use structured replies, by sending
2735 "NBD_OPT_STRUCTURED_REPLY". This behaves like the synchronous counter‐
2736 part nbd_opt_structured_reply(3), except that it does not wait for the
2737 server's response.
2738 To determine when the request completes, wait for nbd_aio_is_connect‐
2740 ing(3) to return false. Or supply the optional "completion_callback"
2741 which will be invoked as described in "Completion callbacks" in
2742 libnbd(3), except that it is automatically retired regardless of return
2743 value. Note that detecting whether the server returns an error (as is
2744 done by the return value of the synchronous counterpart) is only possi‐
2745 ble with a completion callback.
2746 val aio_opt_list : ?completion:(int Stdlib.ref -> int) -> t -> (string
2750 -> string -> int) -> unit
2751 NBD.aio_opt_list t ?completion list
2754 request the server to list all exports during negotiation
2756 Request that the server list all exports that it supports. This can
2758 only be used if nbd_set_opt_mode(3) enabled option mode.
2759 To determine when the request completes, wait for nbd_aio_is_connect‐
2761 ing(3) to return false. Or supply the optional "completion_callback"
2762 which will be invoked as described in "Completion callbacks" in
2763 libnbd(3), except that it is automatically retired regardless of return
2764 value. Note that detecting whether the server returns an error (as is
2765 done by the return value of the synchronous counterpart) is only possi‐
2766 ble with a completion callback.
2767 val aio_opt_info : ?completion:(int Stdlib.ref -> int) -> t -> unit
2771 NBD.aio_opt_info t ?completion
2774 request the server for information about an export
2776 Request that the server supply information about the export name previ‐
2778 ously specified by the most recent nbd_set_export_name(3) or nbd_con‐
2779 nect_uri(3). This can only be used if nbd_set_opt_mode(3) enabled op‐
2780 tion mode.
2781 To determine when the request completes, wait for nbd_aio_is_connect‐
2783 ing(3) to return false. Or supply the optional "completion_callback"
2784 which will be invoked as described in "Completion callbacks" in
2785 libnbd(3), except that it is automatically retired regardless of return
2786 value. Note that detecting whether the server returns an error (as is
2787 done by the return value of the synchronous counterpart) is only possi‐
2788 ble with a completion callback.
2789 val aio_opt_list_meta_context : ?completion:(int Stdlib.ref -> int) ->
2793 t -> (string -> int) -> int
2794 NBD.aio_opt_list_meta_context t ?completion context
2797 request list of available meta contexts, using implicit query
2799 Request that the server list available meta contexts associated with
2801 the export previously specified by the most recent nbd_set_ex‐
2802 port_name(3) or nbd_connect_uri(3), and with a list of queries from
2803 prior calls to nbd_add_meta_context(3) (see nbd_aio_opt_list_meta_con‐
2804 text_queries(3) if you want to supply an explicit query list instead).
2805 This can only be used if nbd_set_opt_mode(3) enabled option mode.
2806 To determine when the request completes, wait for nbd_aio_is_connect‐
2808 ing(3) to return false. Or supply the optional "completion_callback"
2809 which will be invoked as described in "Completion callbacks" in
2810 libnbd(3), except that it is automatically retired regardless of return
2811 value. Note that detecting whether the server returns an error (as is
2812 done by the return value of the synchronous counterpart) is only possi‐
2813 ble with a completion callback.
2814 val aio_opt_list_meta_context_queries : ?completion:(int Stdlib.ref ->
2818 int) -> t -> string list -> (string -> int) -> int
2819 NBD.aio_opt_list_meta_context_queries t ?completion queries context
2822 request list of available meta contexts, using explicit query
2824 Request that the server list available meta contexts associated with
2826 the export previously specified by the most recent nbd_set_ex‐
2827 port_name(3) or nbd_connect_uri(3), and with an explicit list of
2828 queries provided as a parameter (see nbd_aio_opt_list_meta_context(3)
2829 if you want to reuse an implicit query list instead). This can only be
2830 used if nbd_set_opt_mode(3) enabled option mode.
2831 To determine when the request completes, wait for nbd_aio_is_connect‐
2833 ing(3) to return false. Or supply the optional "completion_callback"
2834 which will be invoked as described in "Completion callbacks" in
2835 libnbd(3), except that it is automatically retired regardless of return
2836 value. Note that detecting whether the server returns an error (as is
2837 done by the return value of the synchronous counterpart) is only possi‐
2838 ble with a completion callback.
2839 val aio_opt_set_meta_context : ?completion:(int Stdlib.ref -> int) -> t
2843 -> (string -> int) -> int
2844 NBD.aio_opt_set_meta_context t ?completion context
2847 select specific meta contexts, with implicit query list
2849 Request that the server supply all recognized meta contexts registered
2851 through prior calls to nbd_add_meta_context(3), in conjunction with the
2852 export previously specified by the most recent nbd_set_export_name(3)
2853 or nbd_connect_uri(3). This can only be used if nbd_set_opt_mode(3) en‐
2854 abled option mode. Normally, this function is redundant, as
2855 nbd_opt_go(3) automatically does the same task if structured replies
2856 have already been negotiated. But manual control over meta context re‐
2857 quests can be useful for fine-grained testing of how a server handles
2858 unusual negotiation sequences. Often, use of this function is coupled
2859 with nbd_set_request_meta_context(3) to bypass the automatic context
2860 request normally performed by nbd_opt_go(3).
2861 To determine when the request completes, wait for nbd_aio_is_connect‐
2863 ing(3) to return false. Or supply the optional "completion_callback"
2864 which will be invoked as described in "Completion callbacks" in
2865 libnbd(3), except that it is automatically retired regardless of return
2866 value. Note that detecting whether the server returns an error (as is
2867 done by the return value of the synchronous counterpart) is only possi‐
2868 ble with a completion callback.
2869 val aio_opt_set_meta_context_queries : ?completion:(int Stdlib.ref ->
2873 int) -> t -> string list -> (string -> int) -> int
2874 NBD.aio_opt_set_meta_context_queries t ?completion queries context
2877 select specific meta contexts, with explicit query list
2879 Request that the server supply all recognized meta contexts passed in
2881 through "queries", in conjunction with the export previously specified
2882 by the most recent nbd_set_export_name(3) or nbd_connect_uri(3). This
2883 can only be used if nbd_set_opt_mode(3) enabled option mode. Normally,
2884 this function is redundant, as nbd_opt_go(3) automatically does the
2885 same task if structured replies have already been negotiated. But man‐
2886 ual control over meta context requests can be useful for fine-grained
2887 testing of how a server handles unusual negotiation sequences. Often,
2888 use of this function is coupled with nbd_set_request_meta_context(3) to
2889 bypass the automatic context request normally performed by
2890 nbd_opt_go(3).
2891 To determine when the request completes, wait for nbd_aio_is_connect‐
2893 ing(3) to return false. Or supply the optional "completion_callback"
2894 which will be invoked as described in "Completion callbacks" in
2895 libnbd(3), except that it is automatically retired regardless of return
2896 value. Note that detecting whether the server returns an error (as is
2897 done by the return value of the synchronous counterpart) is only possi‐
2898 ble with a completion callback.
2899 val aio_pread : ?completion:(int Stdlib.ref -> int) ->
2903 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> cookie
2904 NBD.aio_pread t ?completion ?flags buf offset
2907 read from the NBD server
2909 Issue a read command to the NBD server.
2911 To check if the command completed, call nbd_aio_command_completed(3).
2913 Or supply the optional "completion_callback" which will be invoked as
2914 described in "Completion callbacks" in libnbd(3).
2915 Note that you must ensure "buf" is valid until the command has com‐
2917 pleted. Furthermore, if the "error" parameter to "completion_callback"
2918 is set or if nbd_aio_command_completed(3) reports failure, and if
2919 nbd_get_pread_initialize(3) returns true, then libnbd sanitized "buf",
2920 but it is unspecified whether the contents of "buf" will read as zero
2921 or as partial results from the server. If nbd_get_pread_initialize(3)
2922 returns false, then libnbd did not sanitize "buf", and the contents are
2923 undefined on failure.
2924 Other parameters behave as documented in nbd_pread(3).
2926 By default, libnbd will reject attempts to use this function with pa‐
2928 rameters that are likely to result in server failure, such as request‐
2929 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2930 used to alter which scenarios should await a server reply rather than
2931 failing fast.
2932 val aio_pread_structured : ?completion:(int Stdlib.ref -> int) ->
2936 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> (bytes -> int64 ->
2937 int -> int Stdlib.ref -> int) -> cookie
2938 NBD.aio_pread_structured t ?completion ?flags buf offset chunk
2941 read from the NBD server
2943 Issue a read command to the NBD server.
2945 To check if the command completed, call nbd_aio_command_completed(3).
2947 Or supply the optional "completion_callback" which will be invoked as
2948 described in "Completion callbacks" in libnbd(3).
2949 Note that you must ensure "buf" is valid until the command has com‐
2951 pleted. Furthermore, if the "error" parameter to "completion_callback"
2952 is set or if nbd_aio_command_completed(3) reports failure, and if
2953 nbd_get_pread_initialize(3) returns true, then libnbd sanitized "buf",
2954 but it is unspecified whether the contents of "buf" will read as zero
2955 or as partial results from the server. If nbd_get_pread_initialize(3)
2956 returns false, then libnbd did not sanitize "buf", and the contents are
2957 undefined on failure.
2958 Other parameters behave as documented in nbd_pread_structured(3).
2960 By default, libnbd will reject attempts to use this function with pa‐
2962 rameters that are likely to result in server failure, such as request‐
2963 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2964 used to alter which scenarios should await a server reply rather than
2965 failing fast.
2966 val aio_pwrite : ?completion:(int Stdlib.ref -> int) ->
2970 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> cookie
2971 NBD.aio_pwrite t ?completion ?flags buf offset
2974 write to the NBD server
2976 Issue a write command to the NBD server.
2978 To check if the command completed, call nbd_aio_command_completed(3).
2980 Or supply the optional "completion_callback" which will be invoked as
2981 described in "Completion callbacks" in libnbd(3).
2982 Note that you must ensure "buf" is valid until the command has com‐
2984 pleted. Other parameters behave as documented in nbd_pwrite(3).
2985 By default, libnbd will reject attempts to use this function with pa‐
2987 rameters that are likely to result in server failure, such as request‐
2988 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2989 used to alter which scenarios should await a server reply rather than
2990 failing fast.
2991 val aio_disconnect : ?flags:CMD_FLAG.t list -> t -> unit
2995 NBD.aio_disconnect t ?flags
2998 disconnect from the NBD server
3000 Issue the disconnect command to the NBD server. This is not a normal
3002 command because NBD servers are not obliged to send a reply. Instead
3003 you should wait for nbd_aio_is_closed(3) to become true on the connec‐
3004 tion. Once this command is issued, you cannot issue any further com‐
3005 mands.
3006 Although libnbd does not prevent you from issuing this command while
3008 still waiting on the replies to previous commands, the NBD protocol
3009 recommends that you wait until there are no other commands in flight
3010 (see nbd_aio_in_flight(3)), to give the server a better chance at a
3011 clean shutdown.
3012 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
3014 tocol extensions). There is no direct synchronous counterpart; however,
3015 nbd_shutdown(3) will call this function if appropriate.
3016 val aio_flush : ?completion:(int Stdlib.ref -> int) ->
3020 ?flags:CMD_FLAG.t list -> t -> cookie
3021 NBD.aio_flush t ?completion ?flags
3024 send flush command to the NBD server
3026 Issue the flush command to the NBD server.
3028 To check if the command completed, call nbd_aio_command_completed(3).
3030 Or supply the optional "completion_callback" which will be invoked as
3031 described in "Completion callbacks" in libnbd(3).
3032 Other parameters behave as documented in nbd_flush(3).
3034 By default, libnbd will reject attempts to use this function with pa‐
3036 rameters that are likely to result in server failure, such as request‐
3037 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
3038 used to alter which scenarios should await a server reply rather than
3039 failing fast.
3040 val aio_trim : ?completion:(int Stdlib.ref -> int) -> ?flags:CMD_FLAG.t
3044 list -> t -> int64 -> int64 -> cookie
3045 NBD.aio_trim t ?completion ?flags count offset
3048 send trim command to the NBD server
3050 Issue a trim command to the NBD server.
3052 To check if the command completed, call nbd_aio_command_completed(3).
3054 Or supply the optional "completion_callback" which will be invoked as
3055 described in "Completion callbacks" in libnbd(3).
3056 Other parameters behave as documented in nbd_trim(3).
3058 By default, libnbd will reject attempts to use this function with pa‐
3060 rameters that are likely to result in server failure, such as request‐
3061 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
3062 used to alter which scenarios should await a server reply rather than
3063 failing fast.
3064 val aio_cache : ?completion:(int Stdlib.ref -> int) ->
3068 ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> cookie
3069 NBD.aio_cache t ?completion ?flags count offset
3072 send cache (prefetch) command to the NBD server
3074 Issue the cache (prefetch) command to the NBD server.
3076 To check if the command completed, call nbd_aio_command_completed(3).
3078 Or supply the optional "completion_callback" which will be invoked as
3079 described in "Completion callbacks" in libnbd(3).
3080 Other parameters behave as documented in nbd_cache(3).
3082 By default, libnbd will reject attempts to use this function with pa‐
3084 rameters that are likely to result in server failure, such as request‐
3085 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
3086 used to alter which scenarios should await a server reply rather than
3087 failing fast.
3088 val aio_zero : ?completion:(int Stdlib.ref -> int) -> ?flags:CMD_FLAG.t
3092 list -> t -> int64 -> int64 -> cookie
3093 NBD.aio_zero t ?completion ?flags count offset
3096 send write zeroes command to the NBD server
3098 Issue a write zeroes command to the NBD server.
3100 To check if the command completed, call nbd_aio_command_completed(3).
3102 Or supply the optional "completion_callback" which will be invoked as
3103 described in "Completion callbacks" in libnbd(3).
3104 Other parameters behave as documented in nbd_zero(3).
3106 By default, libnbd will reject attempts to use this function with pa‐
3108 rameters that are likely to result in server failure, such as request‐
3109 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
3110 used to alter which scenarios should await a server reply rather than
3111 failing fast.
3112 val aio_block_status : ?completion:(int Stdlib.ref -> int) ->
3116 ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> (string -> int64 ->
3117 int64 array -> int Stdlib.ref -> int) -> cookie
3118 NBD.aio_block_status t ?completion ?flags count offset extent
3121 send block status command to the NBD server
3123 Send the block status command to the NBD server.
3125 To check if the command completed, call nbd_aio_command_completed(3).
3127 Or supply the optional "completion_callback" which will be invoked as
3128 described in "Completion callbacks" in libnbd(3).
3129 Other parameters behave as documented in nbd_block_status(3).
3131 By default, libnbd will reject attempts to use this function with pa‐
3133 rameters that are likely to result in server failure, such as request‐
3134 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
3135 used to alter which scenarios should await a server reply rather than
3136 failing fast.
3137 val aio_get_fd : t -> Unix.file_descr
3141 NBD.aio_get_fd t
3144 return file descriptor associated with this connection
3146 Return the underlying file descriptor associated with this connection.
3148 You can use this to check if the file descriptor is ready for reading
3149 or writing and call nbd_aio_notify_read(3) or nbd_aio_notify_write(3).
3150 See also nbd_aio_get_direction(3). Do not do anything else with the
3151 file descriptor.
3152 val aio_get_direction : t -> int
3156 NBD.aio_get_direction t
3159 return the read or write direction
3161 Return the current direction of this connection, which means whether we
3163 are next expecting to read data from the server, write data to the
3164 server, or both. It returns
3165 0 We are not expected to interact with the server file descriptor
3167 from the current state. It is not worth attempting to use poll(2); if
3168 the connection is not dead, then state machine progress must instead
3169 come from some other means such as nbd_aio_connect(3).
3170 "LIBNBD_AIO_DIRECTION_READ" = 1 We are expected next to read from the
3172 server. If using poll(2) you would set "events = POLLIN". If "revents"
3173 returns "POLLIN" or "POLLHUP" you would then call nbd_aio_no‐
3174 tify_read(3).
3175 Note that once libnbd reaches nbd_aio_is_ready(3), this direction is
3177 returned even when there are no commands in flight (see
3178 nbd_aio_in_flight(3)). In a single-threaded use of libnbd, it is not
3179 worth polling until after issuing a command, as otherwise the server
3180 will never wake up the poll. In a multi-threaded scenario, you can have
3181 one thread begin a polling loop prior to any commands, but any other
3182 thread that issues a command will need a way to kick the polling thread
3183 out of poll in case issuing the command changes the needed polling di‐
3184 rection. Possible ways to do this include polling for activity on a
3185 pipe-to-self, or using pthread_kill(3) to send a signal that is masked
3186 except during ppoll(2).
3187 "LIBNBD_AIO_DIRECTION_WRITE" = 2 We are expected next to write to the
3189 server. If using poll(2) you would set "events = POLLOUT". If "revents"
3190 returns "POLLOUT" you would then call nbd_aio_notify_write(3).
3191 "LIBNBD_AIO_DIRECTION_BOTH" = 3 We are expected next to either read or
3193 write to the server. If using poll(2) you would set "events =
3194 POLLIN|POLLOUT". If only one of "POLLIN" or "POLLOUT" is returned, then
3195 see above. However, if both are returned, it is better to call only
3196 nbd_aio_notify_read(3), as processing the server's reply may change the
3197 state of the connection and invalidate the need to write more commands.
3198 val aio_notify_read : t -> unit
3202 NBD.aio_notify_read t
3205 notify that the connection is readable
3207 Send notification to the state machine that the connection is readable.
3209 Typically this is called after your main loop has detected that the
3210 file descriptor associated with this connection is readable.
3211 val aio_notify_write : t -> unit
3215 NBD.aio_notify_write t
3218 notify that the connection is writable
3220 Send notification to the state machine that the connection is writable.
3222 Typically this is called after your main loop has detected that the
3223 file descriptor associated with this connection is writable.
3224 val aio_is_created : t -> bool
3228 NBD.aio_is_created t
3231 check if the connection has just been created
3233 Return true if this connection has just been created. This is the
3235 state before the handle has started connecting to a server. In this
3236 state the handle can start to be connected by calling functions such as
3237 nbd_aio_connect(3).
3238 val aio_is_connecting : t -> bool
3242 NBD.aio_is_connecting t
3245 check if the connection is connecting or handshaking
3247 Return true if this connection is connecting to the server or in the
3249 process of handshaking and negotiating options which happens before the
3250 handle becomes ready to issue commands (see nbd_aio_is_ready(3)).
3251 val aio_is_negotiating : t -> bool
3255 NBD.aio_is_negotiating t
3258 check if connection is ready to send handshake option
3260 Return true if this connection is ready to start another option negoti‐
3262 ation command while handshaking with the server. An option command will
3263 move back to the connecting state (see nbd_aio_is_connecting(3)). Note
3264 that this state cannot be reached unless requested by
3265 nbd_set_opt_mode(3), and even then it only works with newstyle servers;
3266 an oldstyle server will skip straight to nbd_aio_is_ready(3).
3267 val aio_is_ready : t -> bool
3271 NBD.aio_is_ready t
3274 check if the connection is in the ready state
3276 Return true if this connection is connected to the NBD server, the
3278 handshake has completed, and the connection is idle or waiting for a
3279 reply. In this state the handle is ready to issue commands.
3280 val aio_is_processing : t -> bool
3284 NBD.aio_is_processing t
3287 check if the connection is processing a command
3289 Return true if this connection is connected to the NBD server, the
3291 handshake has completed, and the connection is processing commands (ei‐
3292 ther writing out a request or reading a reply).
3293 Note the ready state (nbd_aio_is_ready(3)) is not included. In the
3295 ready state commands may be *in flight* (the *server* is processing
3296 them), but libnbd is not processing them.
3297 val aio_is_dead : t -> bool
3301 NBD.aio_is_dead t
3304 check if the connection is dead
3306 Return true if the connection has encountered a fatal error and is
3308 dead. In this state the handle may only be closed. There is no way to
3309 recover a handle from the dead state.
3310 val aio_is_closed : t -> bool
3314 NBD.aio_is_closed t
3317 check if the connection is closed
3319 Return true if the connection has closed. There is no way to reconnect
3321 a closed connection. Instead you must close the whole handle.
3322 val aio_command_completed : t -> int64 -> bool
3326 NBD.aio_command_completed t cookie
3329 check if the command completed
3331 Return true if the command completed. If this function returns true
3333 then the command was successful and it has been retired. Return false
3334 if the command is still in flight. This can also fail with an error in
3335 case the command failed (in this case the command is also retired). A
3336 command is retired either via this command, or by using a completion
3337 callback which returns 1.
3338 The "cookie" parameter is the positive unique 64 bit cookie for the
3340 command, as returned by a call such as nbd_aio_pread(3).
3341 val aio_peek_command_completed : t -> int64
3345 NBD.aio_peek_command_completed t
3348 check if any command has completed
3350 Return the unique positive 64 bit cookie of the first non-retired but
3352 completed command, 0 if there are in-flight commands but none of them
3353 are awaiting retirement, or -1 on error including when there are no
3354 in-flight commands. Any cookie returned by this function must still be
3355 passed to nbd_aio_command_completed(3) to actually retire the command
3356 and learn whether the command was successful.
3357 val aio_in_flight : t -> int
3361 NBD.aio_in_flight t
3364 check how many aio commands are still in flight
3366 Return the number of in-flight aio commands that are still awaiting a
3368 response from the server before they can be retired. If this returns a
3369 non-zero value when requesting a disconnect from the server (see
3370 nbd_aio_disconnect(3) and nbd_shutdown(3)), libnbd does not try to wait
3371 for those commands to complete gracefully; if the server strands com‐
3372 mands while shutting down, nbd_aio_command_completed(3) will report
3373 those commands as failed with a status of "ENOTCONN".
3374 val connection_state : t -> string
3378 NBD.connection_state t
3381 return string describing the state of the connection
3383 Returns a descriptive string for the state of the connection. This can
3385 be used for debugging or troubleshooting, but you should not rely on
3386 the state of connections since it may change in future versions.
3387 val get_package_name : t -> string
3391 NBD.get_package_name t
3394 return the name of the library
3396 Returns the name of the library, always "libnbd" unless the library was
3398 modified with another name at compile time.
3399 val get_version : t -> string
3403 NBD.get_version t
3406 return the version of the library
3408 Return the version of libnbd. This is returned as a string in the form
3410 "major.minor.release" where each of major, minor and release is a small
3411 positive integer. For example:
3412 minor ↓ "1.0.3" ↑ ↑ major release
3414 major = 0 The major number was 0 for the early experimental versions of
3416 libnbd where we still had an unstable API.
3417 major = 1 The major number is 1 for the versions of libnbd with a
3419 long-term stable API and ABI. It is not anticipated that major will be
3420 any number other than 1.
3421 minor = 0, 2, ... (even) The minor number is even for stable releases.
3423 minor = 1, 3, ... (odd) The minor number is odd for development ver‐
3425 sions. Note that new APIs added in a development version remain exper‐
3426 imental and subject to change in that branch until they appear in a
3427 stable release.
3428 release The release number is incremented for each release along a par‐
3430 ticular branch.
3431 val kill_subprocess : t -> int -> unit
3435 NBD.kill_subprocess t signum
3438 kill server running as a subprocess
3440 This call may be used to kill the server running as a subprocess that
3442 was previously created using nbd_connect_command(3). You do not need to
3443 use this call. It is only needed if the server does not exit when the
3444 socket is closed.
3445 The "signum" parameter is the optional signal number to send (see sig‐
3447 nal(7)). If "signum" is 0 then "SIGTERM" is sent.
3448 val supports_tls : t -> bool
3452 NBD.supports_tls t
3455 true if libnbd was compiled with support for TLS
3457 Returns true if libnbd was compiled with gnutls which is required to
3459 support TLS encryption, or false if not.
3460 val supports_vsock : t -> bool
3464 NBD.supports_vsock t
3467 true if libnbd was compiled with support for AF_VSOCK
3469 Returns true if libnbd was compiled with support for the "AF_VSOCK"
3471 family of sockets, or false if not.
3472 Note that on the Linux operating system, this returns true if there is
3474 compile-time support, but you may still need runtime support for some
3475 aspects of AF_VSOCK usage; for example, use of "VMADDR_CID_LOCAL" as
3476 the server name requires that the *vsock_loopback* kernel module is
3477 loaded.
3478 val supports_uri : t -> bool
3482 NBD.supports_uri t
3485 true if libnbd was compiled with support for NBD URIs
3487 Returns true if libnbd was compiled with libxml2 which is required to
3489 support NBD URIs, or false if not.
3490 val get_uri : t -> string
3494 NBD.get_uri t
3497 construct an NBD URI for a connection
3499 This makes a best effort attempt to construct an NBD URI which could be
3501 used to connect back to the same server (using nbd_connect_uri(3)).
3502 In some cases there is not enough information in the handle to success‐
3504 fully create a URI (eg. if you connected with nbd_connect_socket(3)).
3505 In such cases the call returns "NULL" and further diagnostic informa‐
3506 tion is available via nbd_get_errno(3) and nbd_get_error(3) as usual.
3507 Even if a URI is returned it is not guaranteed to work, and it may not
3509 be optimal.
3510OCamldoc 2023-09-26 NBD(3)