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 type extent = int64 * int64
50 Length and flags of an extent in NBD.block_status_64 callback.
53 module TLS : sig end
56 module SIZE : sig end
61 module CMD_FLAG : sig end
66 module HANDSHAKE_FLAG : sig end
71 module STRICT : sig end
76 module ALLOW_TRANSPORT : sig end
81 module SHUTDOWN : sig end
86 val aio_direction_read : int32
92 val aio_direction_write : int32
97 val aio_direction_both : int32
102 val read_data : int32
107 val read_hole : int32
112 val read_error : int32
117 val namespace_base : string
122 val context_base_allocation : string
127 val state_hole : int32
132 val state_zero : int32
137 val namespace_qemu : string
142 val context_qemu_dirty_bitmap : string
147 val state_dirty : int32
152 val context_qemu_allocation_depth : string
157 module Buffer : sig end
161 Persistent buffer used in AIO calls.
164 val errno_of_unix_error : Unix.error -> int
168 Return the raw C errno corresponding to a Unix.error . This can be
170 used in callbacks to update the int ref parameter.
171 type t
174 The handle.
177 val create : unit -> t
181 Create a new handle.
183 val close : t -> unit
187 Close a handle.
189 Handles can also be closed by the garbage collector when they become
191 unreachable. This call is used only if you want to force the handle to
192 close now and reclaim resources immediately.
193 val with_handle : (t -> 'a) -> 'a
197 Wrapper around NBD.create . It calls the function parameter with a
199 newly created handle, and ensures that NBD.close is always called even
200 if the function throws an exception.
201 Use this when it is essential that the handle is closed in order to
203 free up external resources in a timely manner; for example if running
204 the server as a subprocess and you want to ensure that the subprocess
205 is always killed; or if you need to disconnect from the server before
206 continuing with another operation.
207 val set_debug : t -> bool -> unit
211 NBD.set_debug t debug
214 set or clear the debug flag
216 Set or clear the debug flag. When debugging is enabled, debugging mes‐
218 sages from the library are printed to stderr, unless a debugging call‐
219 back has been defined too (see nbd_set_debug_callback(3)) in which case
220 they are sent to that function. This flag defaults to false on newly
221 created handles, except if "LIBNBD_DEBUG=1" is set in the environment
222 in which case it defaults to true.
223 val get_debug : t -> bool
227 NBD.get_debug t
230 return the state of the debug flag
232 Return the state of the debug flag on this handle.
234 val set_debug_callback : t -> (string -> string -> int) -> unit
238 NBD.set_debug_callback t debug
241 set the debug callback
243 Set the debug callback. This function is called when the library emits
245 debug messages, when debugging is enabled on a handle. The callback pa‐
246 rameters are "user_data" passed to this function, the name of the
247 libnbd function emitting the debug message ("context"), and the message
248 itself ("msg"). If no debug callback is set on a handle then messages
249 are printed on "stderr".
250 The callback should not call "nbd_*" APIs on the same handle since it
252 can be called while holding the handle lock and will cause a deadlock.
253 val clear_debug_callback : t -> unit
257 NBD.clear_debug_callback t
260 clear the debug callback
262 Remove the debug callback if one was previously associated with the
264 handle (with nbd_set_debug_callback(3)). If no callback was associated
265 this does nothing.
266 val stats_bytes_sent : t -> int64
270 NBD.stats_bytes_sent t
273 statistics of bytes sent over connection so far
275 Return the number of bytes that the client has sent to the server.
277 This tracks the plaintext bytes utilized by the NBD protocol; it may
279 differ from the number of bytes actually sent over the connection, par‐
280 ticularly when TLS is in use.
281 val stats_chunks_sent : t -> int64
285 NBD.stats_chunks_sent t
288 statistics of chunks sent over connection so far
290 Return the number of chunks that the client has sent to the server,
292 where a chunk is a group of bytes delineated by a magic number that
293 cannot be further subdivided without breaking the protocol.
294 This number does not necessarily relate to the number of API calls
296 made, nor to the number of TCP packets sent over the connection.
297 val stats_bytes_received : t -> int64
301 NBD.stats_bytes_received t
304 statistics of bytes received over connection so far
306 Return the number of bytes that the client has received from the
308 server.
309 This tracks the plaintext bytes utilized by the NBD protocol; it may
311 differ from the number of bytes actually received over the connection,
312 particularly when TLS is in use.
313 val stats_chunks_received : t -> int64
317 NBD.stats_chunks_received t
320 statistics of chunks received over connection so far
322 Return the number of chunks that the client has received from the
324 server, where a chunk is a group of bytes delineated by a magic number
325 that cannot be further subdivided without breaking the protocol.
326 This number does not necessarily relate to the number of API calls
328 made, nor to the number of TCP packets received over the connection.
329 val set_handle_name : t -> string -> unit
333 NBD.set_handle_name t handle_name
336 set the handle name
338 Handles have a name which is unique within the current process. The
340 handle name is used in debug output.
341 Handle names are normally generated automatically and have the form
343 "nbd1", "nbd2", etc., but you can optionally use this call to give the
344 handles a name which is meaningful for your application to make debug‐
345 ging output easier to understand.
346 val get_handle_name : t -> string
350 NBD.get_handle_name t
353 get the handle name
355 Get the name of the handle. If it was previously set by calling
357 nbd_set_handle_name(3) then this returns the name that was set. Other‐
358 wise it will return a generic name like "nbd1", "nbd2", etc.
359 val set_private_data : t -> int -> int
363 NBD.set_private_data t private_data
366 set the per-handle private data
368 Handles contain a private data field for applications to use for any
370 purpose.
371 When calling libnbd from C, the type of this field is "uintptr_t" so it
373 can be used to store an unsigned integer or a pointer.
374 In non-C bindings it can be used to store an unsigned integer.
376 This function sets the value of this field and returns the old value
378 (or 0 if it was not previously set).
379 val get_private_data : t -> int
383 NBD.get_private_data t
386 get the per-handle private data
388 Return the value of the private data field set previously by a call to
390 nbd_set_private_data(3) (or 0 if it was not previously set).
391 val set_export_name : t -> string -> unit
395 NBD.set_export_name t export_name
398 set the export name
400 For servers which require an export name or can serve different content
402 on different exports, set the "export_name" to connect to. The default
403 is the empty string "".
404 This is only relevant when connecting to servers using the newstyle
406 protocol as the oldstyle protocol did not support export names. The NBD
407 protocol limits export names to 4096 bytes, but servers may not support
408 the full length. The encoding of export names is always UTF-8.
409 When option mode is not in use, the export name must be set before be‐
411 ginning a connection. However, when nbd_set_opt_mode(3) has enabled op‐
412 tion mode, it is possible to change the export name prior to
413 nbd_opt_go(3). In particular, the use of nbd_opt_list(3) during negoti‐
414 ation can be used to determine a name the server is likely to accept,
415 and nbd_opt_info(3) can be used to learn details about an export before
416 connecting.
417 This call may be skipped if using nbd_connect_uri(3) to connect to a
419 URI that includes an export name.
420 val get_export_name : t -> string
424 NBD.get_export_name t
427 get the export name
429 Get the export name associated with the handle. This is the name that
431 libnbd requests; see nbd_get_canonical_export_name(3) for determining
432 if the server has a different canonical name for the given export (most
433 common when requesting the default export name of an empty string "")
434 val set_request_block_size : t -> bool -> unit
438 NBD.set_request_block_size t request
441 control whether NBD_OPT_GO requests block size
443 By default, when connecting to an export, libnbd requests that the
445 server report any block size restrictions. The NBD protocol states that
446 a server may supply block sizes regardless of whether the client re‐
447 quests them, and libnbd will report those block sizes (see
448 nbd_get_block_size(3)); conversely, if a client does not request block
449 sizes, the server may reject the connection instead of dealing with a
450 client sending unaligned requests. This function makes it possible to
451 test server behavior by emulating older clients.
452 Note that even when block size is requested, the server is not obli‐
454 gated to provide any. Furthermore, if block sizes are provided (whether
455 or not the client requested them), libnbd enforces alignment to those
456 sizes unless nbd_set_strict_mode(3) is used to bypass client-side
457 safety checks.
458 val get_request_block_size : t -> bool
462 NBD.get_request_block_size t
465 see if NBD_OPT_GO requests block size
467 Return the state of the block size request flag on this handle.
469 val set_full_info : t -> bool -> unit
473 NBD.set_full_info t request
476 control whether NBD_OPT_GO requests extra details
478 By default, when connecting to an export, libnbd only requests the de‐
480 tails it needs to service data operations. The NBD protocol says that a
481 server can supply optional information, such as a canonical name of the
482 export (see nbd_get_canonical_export_name(3)) or a description of the
483 export (see nbd_get_export_description(3)), but that a hint from the
484 client makes it more likely for this extra information to be provided.
485 This function controls whether libnbd will provide that hint.
486 Note that even when full info is requested, the server is not obligated
488 to reply with all information that libnbd requested. Similarly, libnbd
489 will ignore any optional server information that libnbd has not yet
490 been taught to recognize. Furthermore, the hint to request block sizes
491 is independently controlled via nbd_set_request_block_size(3).
492 val get_full_info : t -> bool
496 NBD.get_full_info t
499 see if NBD_OPT_GO requests extra details
501 Return the state of the full info request flag on this handle.
503 val get_canonical_export_name : t -> string
507 NBD.get_canonical_export_name t
510 return the canonical export name, if the server has one
512 The NBD protocol permits a server to report an optional canonical ex‐
514 port name, which may differ from the client's request (as set by
515 nbd_set_export_name(3) or nbd_connect_uri(3)). This function accesses
516 any name returned by the server; it may be the same as the client re‐
517 quest, but is more likely to differ when the client requested a connec‐
518 tion to the default export name (an empty string "").
519 Some servers are unlikely to report a canonical name unless the client
521 specifically hinted about wanting it, via nbd_set_full_info(3).
522 val get_export_description : t -> string
526 NBD.get_export_description t
529 return the export description, if the server has one
531 The NBD protocol permits a server to report an optional export descrip‐
533 tion. This function reports any description returned by the server.
534 Some servers are unlikely to report a description unless the client
536 specifically hinted about wanting it, via nbd_set_full_info(3). For
537 qemu-nbd(8), a description is set with *-D*.
538 val set_tls : t -> TLS.t -> unit
542 NBD.set_tls t tls
545 enable or require TLS (authentication and encryption)
547 Enable or require TLS (authenticated and encrypted connections) to the
549 NBD server. The possible settings are:
550 "LIBNBD_TLS_DISABLE" Disable TLS. (The default setting, unless using
552 nbd_connect_uri(3) with a URI that requires TLS).
553 This setting is also necessary if you use nbd_set_opt_mode(3) and want
555 to interact in plaintext with a server that implements the NBD proto‐
556 col's "SELECTIVETLS" mode, prior to enabling TLS with nbd_opt_start‐
557 tls(3). Most NBD servers with TLS support prefer the NBD protocol's
558 "FORCEDTLS" mode, so this sort of manual interaction tends to be useful
559 mainly during integration testing.
560 "LIBNBD_TLS_ALLOW" Enable TLS if possible.
562 This option is insecure (or best effort) in that in some cases it will
564 fall back to an unencrypted and/or unauthenticated connection if TLS
565 could not be established. Use "LIBNBD_TLS_REQUIRE" below if the connec‐
566 tion must be encrypted.
567 Some servers will drop the connection if TLS fails so fallback may not
569 be possible.
570 "LIBNBD_TLS_REQUIRE" Require an encrypted and authenticated TLS connec‐
572 tion. Always fail to connect if the connection is not encrypted and au‐
573 thenticated.
574 As well as calling this you may also need to supply the path to the
576 certificates directory (nbd_set_tls_certificates(3)), the username
577 (nbd_set_tls_username(3)) and/or the Pre-Shared Keys (PSK) file
578 (nbd_set_tls_psk_file(3)). For now, when using nbd_connect_uri(3), any
579 URI query parameters related to TLS are not handled automatically. Set‐
580 ting the level higher than zero will fail if libnbd was not compiled
581 against gnutls; you can test whether this is the case with nbd_sup‐
582 ports_tls(3).
583 val get_tls : t -> TLS.t
587 NBD.get_tls t
590 get the TLS request setting
592 Get the TLS request setting.
594 Note: If you want to find out if TLS was actually negotiated on a par‐
596 ticular connection use nbd_get_tls_negotiated(3) instead.
597 val get_tls_negotiated : t -> bool
601 NBD.get_tls_negotiated t
604 find out if TLS was negotiated on a connection
606 After connecting you may call this to find out if the connection is us‐
608 ing TLS.
609 This is normally useful only if you set the TLS request mode to
611 "LIBNBD_TLS_ALLOW" (see nbd_set_tls(3)), because in this mode we try to
612 use TLS but fall back to unencrypted if it was not available. This
613 function will tell you if TLS was negotiated or not.
614 In "LIBNBD_TLS_REQUIRE" mode (the most secure) the connection would
616 have failed if TLS could not be negotiated. With "LIBNBD_TLS_DISABLE"
617 mode, TLS is not tried automatically; but if the NBD server uses the
618 less-common "SELECTIVETLS" mode, this function reports whether a manual
619 nbd_opt_starttls(3) enabled TLS or if the connection is still plain‐
620 text.
621 val set_tls_certificates : t -> string -> unit
625 NBD.set_tls_certificates t dir
628 set the path to the TLS certificates directory
630 Set the path to the TLS certificates directory. If not set and TLS is
632 used then a compiled in default is used. For root this is
633 "/etc/pki/libnbd/". For non-root this is "$HOME/.pki/libnbd" and
634 "$HOME/.config/pki/libnbd". If none of these directories can be found
635 then the system trusted CAs are used.
636 This function may be called regardless of whether TLS is supported, but
638 will have no effect unless nbd_set_tls(3) is also used to request or
639 require TLS.
640 val set_tls_verify_peer : t -> bool -> unit
644 NBD.set_tls_verify_peer t verify
647 set whether we verify the identity of the server
649 Set this flag to control whether libnbd will verify the identity of the
651 server from the server's certificate and the certificate authority.
652 This defaults to true when connecting to TCP servers using TLS certifi‐
653 cate authentication, and false otherwise.
654 This function may be called regardless of whether TLS is supported, but
656 will have no effect unless nbd_set_tls(3) is also used to request or
657 require TLS.
658 val get_tls_verify_peer : t -> bool
662 NBD.get_tls_verify_peer t
665 get whether we verify the identity of the server
667 Get the verify peer flag.
669 val set_tls_username : t -> string -> unit
673 NBD.set_tls_username t username
676 set the TLS username
678 Set the TLS client username. This is used if authenticating with PSK
680 over TLS is enabled. If not set then the local username is used.
681 This function may be called regardless of whether TLS is supported, but
683 will have no effect unless nbd_set_tls(3) is also used to request or
684 require TLS.
685 val get_tls_username : t -> string
689 NBD.get_tls_username t
692 get the current TLS username
694 Get the current TLS username.
696 val set_tls_psk_file : t -> string -> unit
700 NBD.set_tls_psk_file t filename
703 set the TLS Pre-Shared Keys (PSK) filename
705 Set the TLS Pre-Shared Keys (PSK) filename. This is used if trying to
707 authenticate to the server using with a pre-shared key. There is no de‐
708 fault so if this is not set then PSK authentication cannot be used to
709 connect to the server.
710 This function may be called regardless of whether TLS is supported, but
712 will have no effect unless nbd_set_tls(3) is also used to request or
713 require TLS.
714 val set_request_extended_headers : t -> bool -> unit
718 NBD.set_request_extended_headers t request
721 control use of extended headers
723 By default, libnbd tries to negotiate extended headers with the server,
725 as this protocol extension permits the use of 64-bit zero, trim, and
726 block status actions. However, for integration testing, it can be use‐
727 ful to clear this flag rather than find a way to alter the server to
728 fail the negotiation request.
729 For backwards compatibility, the setting of this knob is ignored if
731 nbd_set_request_structured_replies(3) is also set to false, since the
732 use of extended headers implies structured replies.
733 val get_request_extended_headers : t -> bool
737 NBD.get_request_extended_headers t
740 see if extended headers are attempted
742 Return the state of the request extended headers flag on this handle.
744 Note: If you want to find out if extended headers were actually negoti‐
746 ated on a particular connection use nbd_get_extended_headers_negoti‐
747 ated(3) instead.
748 val get_extended_headers_negotiated : t -> bool
752 NBD.get_extended_headers_negotiated t
755 see if extended headers are in use
757 After connecting you may call this to find out if the connection is us‐
759 ing extended headers. Note that this setting is sticky; this can return
760 true even after a second nbd_opt_extended_headers(3) returns false be‐
761 cause the server detected a duplicate request.
762 When extended headers are not in use, commands are limited to a 32-bit
764 length, even when the libnbd API uses a 64-bit parameter to express the
765 length. But even when extended headers are supported, the server may
766 enforce other limits, visible through nbd_get_block_size(3).
767 Note that when extended headers are negotiated, you should prefer the
769 use of nbd_block_status_64(3) instead of nbd_block_status(3) if any of
770 the meta contexts you requested via nbd_add_meta_context(3) might re‐
771 turn 64-bit status values; however, all of the well-known meta contexts
772 covered by current "LIBNBD_CONTEXT_*" constants only return 32-bit sta‐
773 tus.
774 val set_request_structured_replies : t -> bool -> unit
778 NBD.set_request_structured_replies t request
781 control use of structured replies
783 By default, libnbd tries to negotiate structured replies with the
785 server, as this protocol extension must be in use before
786 nbd_can_meta_context(3) or nbd_can_df(3) can return true. However, for
787 integration testing, it can be useful to clear this flag rather than
788 find a way to alter the server to fail the negotiation request. It is
789 also useful to set this to false prior to using nbd_set_opt_mode(3) if
790 it is desired to control when to send nbd_opt_structured_reply(3) dur‐
791 ing negotiation.
792 Note that setting this knob to false also disables any automatic re‐
794 quest for extended headers.
795 val get_request_structured_replies : t -> bool
799 NBD.get_request_structured_replies t
802 see if structured replies are attempted
804 Return the state of the request structured replies flag on this handle.
806 Note: If you want to find out if structured replies were actually nego‐
808 tiated on a particular connection use nbd_get_structured_replies_nego‐
809 tiated(3) instead.
810 val get_structured_replies_negotiated : t -> bool
814 NBD.get_structured_replies_negotiated t
817 see if structured replies are in use
819 After connecting you may call this to find out if the connection is us‐
821 ing structured replies. Note that this setting is sticky; this can re‐
822 turn true even after a second nbd_opt_structured_reply(3) returns false
823 because the server detected a duplicate request.
824 Note that if the connection negotiates extended headers, this function
826 returns true (as extended headers imply structured replies) even if no
827 explicit request for structured replies was attempted.
828 val set_request_meta_context : t -> bool -> unit
832 NBD.set_request_meta_context t request
835 control whether connect automatically requests meta contexts
837 This function controls whether the act of connecting to an export (all
839 "nbd_connect_*" calls when nbd_set_opt_mode(3) is false, or
840 nbd_opt_go(3) and nbd_opt_info(3) when option mode is enabled) will
841 also try to issue NBD_OPT_SET_META_CONTEXT when the server supports
842 structured replies or extended headers and any contexts were registered
843 by nbd_add_meta_context(3). The default setting is true; however the
844 extra step of negotiating meta contexts is not always desirable: per‐
845 forming both info and go on the same export works without needing to
846 re-negotiate contexts on the second call; integration testing of other
847 servers may benefit from manual invocation of nbd_opt_set_meta_con‐
848 text(3) at other times in the negotiation sequence; and even when using
849 just nbd_opt_info(3), it can be faster to collect the server's results
850 by relying on the callback function passed to nbd_opt_list_meta_con‐
851 text(3) than a series of post-process calls to nbd_can_meta_context(3).
852 Note that this control has no effect if the server does not negotiate
854 structured replies or extended headers, or if the client did not re‐
855 quest any contexts via nbd_add_meta_context(3). Setting this control to
856 false may cause nbd_block_status(3) to fail.
857 val get_request_meta_context : t -> bool
861 NBD.get_request_meta_context t
864 see if connect automatically requests meta contexts
866 Return the state of the automatic meta context request flag on this
868 handle.
869 val set_handshake_flags : t -> HANDSHAKE_FLAG.t list -> unit
873 NBD.set_handshake_flags t flags
876 control use of handshake flags
878 By default, libnbd tries to negotiate all possible handshake flags that
880 are also supported by the server, since omitting a handshake flag can
881 prevent the use of other functionality such as TLS encryption or struc‐
882 tured replies. However, for integration testing, it can be useful to
883 reduce the set of flags supported by the client to test that a particu‐
884 lar server can handle various clients that were compliant to older ver‐
885 sions of the NBD specification.
886 The "flags" argument is a bitmask, including zero or more of the fol‐
888 lowing handshake flags:
889 "LIBNBD_HANDSHAKE_FLAG_FIXED_NEWSTYLE" = 1 The server gracefully han‐
891 dles unknown option requests from the client, rather than disconnect‐
892 ing. Without this flag, a client cannot safely request to use exten‐
893 sions such as TLS encryption or structured replies, as the request may
894 cause an older server to drop the connection.
895 "LIBNBD_HANDSHAKE_FLAG_NO_ZEROES" = 2 If the client is forced to use
897 "NBD_OPT_EXPORT_NAME" instead of the preferred "NBD_OPT_GO", this flag
898 allows the server to send fewer all-zero padding bytes over the connec‐
899 tion.
900 For convenience, the constant "LIBNBD_HANDSHAKE_FLAG_MASK" is available
902 to describe all flags supported by this build of libnbd. Future NBD ex‐
903 tensions may add further flags, which in turn may be enabled by default
904 in newer libnbd. As such, when attempting to disable only one specific
905 bit, it is wiser to first call nbd_get_handshake_flags(3) and modify
906 that value, rather than blindly setting a constant value.
907 val get_handshake_flags : t -> HANDSHAKE_FLAG.t list
911 NBD.get_handshake_flags t
914 see which handshake flags are supported
916 Return the state of the handshake flags on this handle. When the han‐
918 dle has not yet completed a connection (see nbd_aio_is_created(3)),
919 this returns the flags that the client is willing to use, provided the
920 server also advertises those flags. After the connection is ready (see
921 nbd_aio_is_ready(3)), this returns the flags that were actually agreed
922 on between the server and client. If the NBD protocol defines new
923 handshake flags, then the return value from a newer library version may
924 include bits that were undefined at the time of compilation.
925 val set_pread_initialize : t -> bool -> unit
929 NBD.set_pread_initialize t request
932 control whether libnbd pre-initializes read buffers
934 By default, libnbd will pre-initialize the contents of a buffer passed
936 to calls such as nbd_pread(3) to all zeroes prior to checking for any
937 other errors, so that even if a client application passed in an unini‐
938 tialized buffer but fails to check for errors, it will not result in a
939 potential security risk caused by an accidental leak of prior heap con‐
940 tents (see CVE-2022-0485 in libnbd-security(3) for an example of a se‐
941 curity hole in an application built against an earlier version of
942 libnbd that lacked consistent pre-initialization). However, for a
943 client application that has audited that an uninitialized buffer is
944 never dereferenced, or which performs its own pre-initialization,
945 libnbd's sanitization efforts merely pessimize performance (although
946 the time spent in pre-initialization may pale in comparison to time
947 spent waiting on network packets).
948 Calling this function with "request" set to false tells libnbd to skip
950 the buffer initialization step in read commands.
951 val get_pread_initialize : t -> bool
955 NBD.get_pread_initialize t
958 see whether libnbd pre-initializes read buffers
960 Return whether libnbd performs a pre-initialization of a buffer passed
962 to nbd_pread(3) and similar to all zeroes, as set by nbd_set_pread_ini‐
963 tialize(3).
964 val set_strict_mode : t -> STRICT.t list -> unit
968 NBD.set_strict_mode t flags
971 control how strictly to follow NBD protocol
973 By default, libnbd tries to detect requests that would trigger unde‐
975 fined behavior in the NBD protocol, and rejects them client side with‐
976 out causing any network traffic, rather than risking undefined server
977 behavior. However, for integration testing, it can be handy to relax
978 the strictness of libnbd, to coerce it into sending such requests over
979 the network for testing the robustness of the server in dealing with
980 such traffic.
981 The "flags" argument is a bitmask, including zero or more of the fol‐
983 lowing strictness flags:
984 "LIBNBD_STRICT_COMMANDS" = 0x1 If set, this flag rejects client re‐
986 quests that do not comply with the set of advertised server flags (for
987 example, attempting a write on a read-only server, or attempting to use
988 "LIBNBD_CMD_FLAG_FUA" when nbd_can_fua(3) returned false). If clear,
989 this flag relies on the server to reject unexpected commands.
990 "LIBNBD_STRICT_FLAGS" = 0x2 If set, this flag rejects client requests
992 that attempt to set a command flag not recognized by libnbd (those out‐
993 side of "LIBNBD_CMD_FLAG_MASK"), or a flag not normally associated with
994 a command (such as using "LIBNBD_CMD_FLAG_FUA" on a read command). If
995 clear, all flags are sent on to the server, even if sending such a flag
996 may cause the server to change its reply in a manner that confuses
997 libnbd, perhaps causing deadlock or ending the connection.
998 Flags that are known by libnbd as associated with a given command (such
1000 as "LIBNBD_CMD_FLAG_DF" for nbd_pread_structured(3) gated by
1001 nbd_can_df(3)) are controlled by "LIBNBD_STRICT_COMMANDS" instead; and
1002 "LIBNBD_CMD_FLAG_PAYLOAD_LEN" is managed automatically by libnbd unless
1003 "LIBNBD_STRICT_AUTO_FLAG" is disabled.
1004 Note that the NBD protocol only supports 16 bits of command flags, even
1006 though the libnbd API uses "uint32_t"; bits outside of the range per‐
1007 mitted by the protocol are always a client-side error.
1008 "LIBNBD_STRICT_BOUNDS" = 0x4 If set, this flag rejects client requests
1010 that would exceed the export bounds without sending any traffic to the
1011 server. If clear, this flag relies on the server to detect
1012 out-of-bounds requests.
1013 "LIBNBD_STRICT_ZERO_SIZE" = 0x8 If set, this flag rejects client re‐
1015 quests with length 0. If clear, this permits zero-length requests to
1016 the server, which may produce undefined results.
1017 "LIBNBD_STRICT_ALIGN" = 0x10 If set, and the server provided minimum
1019 block sizes (see "LIBNBD_SIZE_MINIMUM" for nbd_get_block_size(3)), this
1020 flag rejects client requests that do not have length and offset aligned
1021 to the server's minimum requirements. If clear, unaligned requests are
1022 sent to the server, where it is up to the server whether to honor or
1023 reject the request.
1024 "LIBNBD_STRICT_PAYLOAD" = 0x20 If set, the client refuses to send a
1026 command to the server with more than libnbd's outgoing payload maximum
1027 (see "LIBNBD_SIZE_PAYLOAD" for nbd_get_block_size(3)), whether or not
1028 the server advertised a block size maximum. If clear, oversize requests
1029 up to 64MiB may be attempted, although requests larger than 32MiB are
1030 liable to cause some servers to disconnect.
1031 "LIBNBD_STRICT_AUTO_FLAG" = 0x40 If set, commands that accept the
1033 "LIBNBD_CMD_FLAG_PAYLOAD_LEN" flag (such as nbd_pwrite(3) and
1034 nbd_block_status_filter(3)) ignore the presence or absence of that flag
1035 from the caller, instead sending the value over the wire that matches
1036 the server's expectations based on whether extended headers were nego‐
1037 tiated when the connection was made. If clear, the caller takes on the
1038 responsibility for whether the payload length flag is set or clear dur‐
1039 ing the affected command, which can be useful during integration test‐
1040 ing but is more likely to lead to undefined behavior.
1041 For convenience, the constant "LIBNBD_STRICT_MASK" is available to de‐
1043 scribe all strictness flags supported by this build of libnbd. Future
1044 versions of libnbd may add further flags, which are likely to be en‐
1045 abled by default for additional client-side filtering. As such, when
1046 attempting to relax only one specific bit while keeping remaining
1047 checks at the client side, it is wiser to first call
1048 nbd_get_strict_mode(3) and modify that value, rather than blindly set‐
1049 ting a constant value.
1050 val get_strict_mode : t -> STRICT.t list
1054 NBD.get_strict_mode t
1057 see which strictness flags are in effect
1059 Return flags indicating which protocol strictness items are being en‐
1061 forced locally by libnbd rather than the server. The return value from
1062 a newer library version may include bits that were undefined at the
1063 time of compilation.
1064 val set_opt_mode : t -> bool -> unit
1068 NBD.set_opt_mode t enable
1071 control option mode, for pausing during option negotiation
1073 Set this flag to true in order to request that a connection command
1075 "nbd_connect_*" will pause for negotiation options rather than proceed‐
1076 ing all the way to the ready state, when communicating with a newstyle
1077 server. This setting has no effect when connecting to an oldstyle
1078 server.
1079 Note that libnbd defaults to attempting "NBD_OPT_STARTTLS",
1081 "NBD_OPT_EXTENDED_HEADERS", and "NBD_OPT_STRUCTURED_REPLY" before let‐
1082 ting you control remaining negotiation steps; if you need control over
1083 these steps as well, first set nbd_set_tls(3) to "LIBNBD_TLS_DISABLE",
1084 and nbd_set_request_extended_headers(3) or nbd_set_request_struc‐
1085 tured_replies(3) to false, before starting the connection attempt.
1086 When option mode is enabled, you have fine-grained control over which
1088 options are negotiated, compared to the default of the server negotiat‐
1089 ing everything on your behalf using settings made before starting the
1090 connection. To leave the mode and proceed on to the ready state, you
1091 must use nbd_opt_go(3) successfully; a failed nbd_opt_go(3) returns to
1092 the negotiating state to allow a change of export name before trying
1093 again. You may also use nbd_opt_abort(3) or nbd_shutdown(3) to end the
1094 connection without finishing negotiation.
1095 val get_opt_mode : t -> bool
1099 NBD.get_opt_mode t
1102 return whether option mode was enabled
1104 Return true if option negotiation mode was enabled on this handle.
1106 val opt_go : t -> unit
1110 NBD.opt_go t
1113 end negotiation and move on to using an export
1115 Request that the server finish negotiation and move on to serving the
1117 export previously specified by the most recent nbd_set_export_name(3)
1118 or nbd_connect_uri(3). This can only be used if nbd_set_opt_mode(3)
1119 enabled option mode.
1120 By default, libnbd will automatically request all meta contexts regis‐
1122 tered by nbd_add_meta_context(3) as part of this call; but this can be
1123 suppressed with nbd_set_request_meta_context(3), particularly if
1124 nbd_opt_set_meta_context(3) was used earlier in the negotiation se‐
1125 quence.
1126 If this fails, the server may still be in negotiation, where it is pos‐
1128 sible to attempt another option such as a different export name; al‐
1129 though older servers will instead have killed the connection.
1130 val opt_abort : t -> unit
1134 NBD.opt_abort t
1137 end negotiation and close the connection
1139 Request that the server finish negotiation, gracefully if possible,
1141 then close the connection. This can only be used if nbd_set_opt_mode(3)
1142 enabled option mode.
1143 val opt_starttls : t -> bool
1147 NBD.opt_starttls t
1150 request the server to initiate TLS
1152 Request that the server initiate a secure TLS connection, by sending
1154 "NBD_OPT_STARTTLS". This can only be used if nbd_set_opt_mode(3) en‐
1155 abled option mode; furthermore, if you use nbd_set_tls(3) to request
1156 anything other than the default of "LIBNBD_TLS_DISABLE", then libnbd
1157 will have already attempted a TLS connection prior to allowing you con‐
1158 trol over option negotiation. This command is disabled if nbd_sup‐
1159 ports_tls(3) reports false.
1160 This function is mainly useful for integration testing of corner cases
1162 in server handling; in particular, misuse of this function when coupled
1163 with a server that is not careful about resetting stateful commands
1164 such as nbd_opt_structured_reply(3) could result in a security hole
1165 (see CVE-2021-3716 against nbdkit, for example). Thus, when security
1166 is a concern, you should instead prefer to use nbd_set_tls(3) with
1167 "LIBNBD_TLS_REQUIRE" and let libnbd negotiate TLS automatically.
1168 This function returns true if the server replies with success, false if
1170 the server replies with an error, and fails only if the server does not
1171 reply (such as for a loss of connection, which can include when the
1172 server rejects credentials supplied during the TLS handshake). Note
1173 that the NBD protocol documents that requesting TLS after it is already
1174 enabled is a client error; most servers will gracefully fail a second
1175 request, but that does not downgrade a TLS session that has already
1176 been established, as reported by nbd_get_tls_negotiated(3).
1177 val opt_extended_headers : t -> bool
1181 NBD.opt_extended_headers t
1184 request the server to enable extended headers
1186 Request that the server use extended headers, by sending "NBD_OPT_EX‐
1188 TENDED_HEADERS". This can only be used if nbd_set_opt_mode(3) enabled
1189 option mode; furthermore, libnbd defaults to automatically requesting
1190 this unless you use nbd_set_request_extended_headers(3) or nbd_set_re‐
1191 quest_structured_replies(3) prior to connecting. This function is
1192 mainly useful for integration testing of corner cases in server han‐
1193 dling.
1194 This function returns true if the server replies with success, false if
1196 the server replies with an error, and fails only if the server does not
1197 reply (such as for a loss of connection). Note that some servers fail a
1198 second request as redundant; libnbd assumes that once one request has
1199 succeeded, then extended headers are supported (as visible by
1200 nbd_get_extended_headers_negotiated(3)) regardless if later calls to
1201 this function return false. If this function returns true, the use of
1202 structured replies is implied.
1203 val opt_structured_reply : t -> bool
1207 NBD.opt_structured_reply t
1210 request the server to enable structured replies
1212 Request that the server use structured replies, by sending
1214 "NBD_OPT_STRUCTURED_REPLY". This can only be used if
1215 nbd_set_opt_mode(3) enabled option mode; furthermore, libnbd defaults
1216 to automatically requesting this unless you use nbd_set_request_struc‐
1217 tured_replies(3) prior to connecting. This function is mainly useful
1218 for integration testing of corner cases in server handling.
1219 This function returns true if the server replies with success, false if
1221 the server replies with an error, and fails only if the server does not
1222 reply (such as for a loss of connection). Note that some servers fail a
1223 second request as redundant; libnbd assumes that once one request has
1224 succeeded, then structured replies are supported (as visible by
1225 nbd_get_structured_replies_negotiated(3)) regardless if later calls to
1226 this function return false. Similarly, a server may fail this request
1227 if extended headers are already negotiated, since extended headers take
1228 priority.
1229 val opt_list : t -> (string -> string -> int) -> int
1233 NBD.opt_list t list
1236 request the server to list all exports during negotiation
1238 Request that the server list all exports that it supports. This can
1240 only be used if nbd_set_opt_mode(3) enabled option mode.
1241 The "list" function is called once per advertised export, with any
1243 "user_data" passed to this function, and with "name" and "description"
1244 supplied by the server. Many servers omit descriptions, in which case
1245 "description" will be an empty string. Remember that it is not safe to
1246 call nbd_set_export_name(3) from within the context of the callback
1247 function; rather, your code must copy any "name" needed for later use
1248 after this function completes. At present, the return value of the
1249 callback is ignored, although a return of -1 should be avoided.
1250 For convenience, when this function succeeds, it returns the number of
1252 exports that were advertised by the server.
1253 Not all servers understand this request, and even when it is under‐
1255 stood, the server might intentionally send an empty list to avoid being
1256 an information leak, may encounter a failure after delivering partial
1257 results, or may refuse to answer more than one query per connection in
1258 the interest of avoiding negotiation that does not resolve. Thus, this
1259 function may succeed even when no exports are reported, or may fail but
1260 have a non-empty list. Likewise, the NBD protocol does not specify an
1261 upper bound for the number of exports that might be advertised, so
1262 client code should be aware that a server may send a lengthy list.
1263 For nbd-server(1) you will need to allow clients to make list requests
1265 by adding "allowlist=true" to the " generic " section of
1266 /etc/nbd-server/config. For qemu-nbd(8), a description is set with
1267 *-D*.
1268 val opt_info : t -> unit
1272 NBD.opt_info t
1275 request the server for information about an export
1277 Request that the server supply information about the export name previ‐
1279 ously specified by the most recent nbd_set_export_name(3) or nbd_con‐
1280 nect_uri(3). This can only be used if nbd_set_opt_mode(3) enabled op‐
1281 tion mode.
1282 If successful, functions like nbd_is_read_only(3) and nbd_get_size(3)
1284 will report details about that export. If nbd_set_request_meta_con‐
1285 text(3) is set (the default) and structured replies or extended headers
1286 were negotiated, it is also valid to use nbd_can_meta_context(3) after
1287 this call. However, it may be more efficient to clear that setting and
1288 manually utilize nbd_opt_list_meta_context(3) with its callback ap‐
1289 proach, for learning which contexts an export supports. In general, if
1290 nbd_opt_go(3) is called next, that call will likely succeed with the
1291 details remaining the same, although this is not guaranteed by all
1292 servers.
1293 Not all servers understand this request, and even when it is under‐
1295 stood, the server might fail the request even when a corresponding
1296 nbd_opt_go(3) would succeed.
1297 val opt_list_meta_context : t -> (string -> int) -> int
1301 NBD.opt_list_meta_context t context
1304 list available meta contexts, using implicit query list
1306 Request that the server list available meta contexts associated with
1308 the export previously specified by the most recent nbd_set_ex‐
1309 port_name(3) or nbd_connect_uri(3), and with a list of queries from
1310 prior calls to nbd_add_meta_context(3) (see nbd_opt_list_meta_con‐
1311 text_queries(3) if you want to supply an explicit query list instead).
1312 This can only be used if nbd_set_opt_mode(3) enabled option mode.
1313 The NBD protocol allows a client to decide how many queries to ask the
1315 server. Rather than taking that list of queries as a parameter to this
1316 function, libnbd reuses the current list of requested meta contexts as
1317 set by nbd_add_meta_context(3); you can use nbd_clear_meta_contexts(3)
1318 to set up a different list of queries. When the list is empty, a server
1319 will typically reply with all contexts that it supports; when the list
1320 is non-empty, the server will reply only with supported contexts that
1321 match the client's request. Note that a reply by the server might be
1322 encoded to represent several feasible contexts within one string,
1323 rather than multiple strings per actual context name that would actu‐
1324 ally succeed during nbd_opt_go(3); so it is still necessary to use
1325 nbd_can_meta_context(3) after connecting to see which contexts are ac‐
1326 tually supported.
1327 The "context" function is called once per server reply, with any
1329 "user_data" passed to this function, and with "name" supplied by the
1330 server. Remember that it is not safe to call nbd_add_meta_context(3)
1331 from within the context of the callback function; rather, your code
1332 must copy any "name" needed for later use after this function com‐
1333 pletes. At present, the return value of the callback is ignored, al‐
1334 though a return of -1 should be avoided.
1335 For convenience, when this function succeeds, it returns the number of
1337 replies returned by the server.
1338 Not all servers understand this request, and even when it is under‐
1340 stood, the server might intentionally send an empty list because it
1341 does not support the requested context, or may encounter a failure af‐
1342 ter delivering partial results. Thus, this function may succeed even
1343 when no contexts are reported, or may fail but have a non-empty list.
1344 Likewise, the NBD protocol does not specify an upper bound for the num‐
1345 ber of replies that might be advertised, so client code should be aware
1346 that a server may send a lengthy list.
1347 val opt_list_meta_context_queries : t -> string list -> (string -> int)
1351 -> int
1352 NBD.opt_list_meta_context_queries t queries context
1355 list available meta contexts, using explicit query list
1357 Request that the server list available meta contexts associated with
1359 the export previously specified by the most recent nbd_set_ex‐
1360 port_name(3) or nbd_connect_uri(3), and with an explicit list of
1361 queries provided as a parameter (see nbd_opt_list_meta_context(3) if
1362 you want to reuse an implicit query list instead). This can only be
1363 used if nbd_set_opt_mode(3) enabled option mode.
1364 The NBD protocol allows a client to decide how many queries to ask the
1366 server. For this function, the list is explicit in the "queries" param‐
1367 eter. When the list is empty, a server will typically reply with all
1368 contexts that it supports; when the list is non-empty, the server will
1369 reply only with supported contexts that match the client's request.
1370 Note that a reply by the server might be encoded to represent several
1371 feasible contexts within one string, rather than multiple strings per
1372 actual context name that would actually succeed during nbd_opt_go(3);
1373 so it is still necessary to use nbd_can_meta_context(3) after connect‐
1374 ing to see which contexts are actually supported.
1375 The "context" function is called once per server reply, with any
1377 "user_data" passed to this function, and with "name" supplied by the
1378 server. Remember that it is not safe to call nbd_add_meta_context(3)
1379 from within the context of the callback function; rather, your code
1380 must copy any "name" needed for later use after this function com‐
1381 pletes. At present, the return value of the callback is ignored, al‐
1382 though a return of -1 should be avoided.
1383 For convenience, when this function succeeds, it returns the number of
1385 replies returned by the server.
1386 Not all servers understand this request, and even when it is under‐
1388 stood, the server might intentionally send an empty list because it
1389 does not support the requested context, or may encounter a failure af‐
1390 ter delivering partial results. Thus, this function may succeed even
1391 when no contexts are reported, or may fail but have a non-empty list.
1392 Likewise, the NBD protocol does not specify an upper bound for the num‐
1393 ber of replies that might be advertised, so client code should be aware
1394 that a server may send a lengthy list.
1395 val opt_set_meta_context : t -> (string -> int) -> int
1399 NBD.opt_set_meta_context t context
1402 select specific meta contexts, using implicit query list
1404 Request that the server supply all recognized meta contexts registered
1406 through prior calls to nbd_add_meta_context(3), in conjunction with the
1407 export previously specified by the most recent nbd_set_export_name(3)
1408 or nbd_connect_uri(3). This can only be used if nbd_set_opt_mode(3) en‐
1409 abled option mode. Normally, this function is redundant, as
1410 nbd_opt_go(3) automatically does the same task if structured replies or
1411 extended headers have already been negotiated. But manual control over
1412 meta context requests can be useful for fine-grained testing of how a
1413 server handles unusual negotiation sequences. Often, use of this func‐
1414 tion is coupled with nbd_set_request_meta_context(3) to bypass the au‐
1415 tomatic context request normally performed by nbd_opt_go(3).
1416 The NBD protocol allows a client to decide how many queries to ask the
1418 server. Rather than taking that list of queries as a parameter to this
1419 function, libnbd reuses the current list of requested meta contexts as
1420 set by nbd_add_meta_context(3); you can use nbd_clear_meta_contexts(3)
1421 to set up a different list of queries (see nbd_opt_set_meta_con‐
1422 text_queries(3) to pass an explicit list of contexts instead). Since
1423 this function is primarily designed for testing servers, libnbd does
1424 not prevent the use of this function on an empty list or when
1425 nbd_set_request_structured_replies(3) has disabled structured replies,
1426 in order to see how a server behaves.
1427 The "context" function is called once per server reply, with any
1429 "user_data" passed to this function, and with "name" supplied by the
1430 server. Additionally, each server name will remain visible through
1431 nbd_can_meta_context(3) until the next attempt at nbd_set_ex‐
1432 port_name(3) or nbd_opt_set_meta_context(3), as well as nbd_opt_go(3)
1433 or nbd_opt_info(3) that trigger an automatic meta context request. Re‐
1434 member that it is not safe to call any "nbd_*" APIs from within the
1435 context of the callback function. At present, the return value of the
1436 callback is ignored, although a return of -1 should be avoided.
1437 For convenience, when this function succeeds, it returns the number of
1439 replies returned by the server.
1440 Not all servers understand this request, and even when it is under‐
1442 stood, the server might intentionally send an empty list because it
1443 does not support the requested context, or may encounter a failure af‐
1444 ter delivering partial results. Thus, this function may succeed even
1445 when no contexts are reported, or may fail but have a non-empty list.
1446 val opt_set_meta_context_queries : t -> string list -> (string -> int)
1450 -> int
1451 NBD.opt_set_meta_context_queries t queries context
1454 select specific meta contexts, using explicit query list
1456 Request that the server supply all recognized meta contexts passed in
1458 through "queries", in conjunction with the export previously specified
1459 by the most recent nbd_set_export_name(3) or nbd_connect_uri(3). This
1460 can only be used if nbd_set_opt_mode(3) enabled option mode. Normally,
1461 this function is redundant, as nbd_opt_go(3) automatically does the
1462 same task if structured replies or extended headers have already been
1463 negotiated. But manual control over meta context requests can be useful
1464 for fine-grained testing of how a server handles unusual negotiation
1465 sequences. Often, use of this function is coupled with nbd_set_re‐
1466 quest_meta_context(3) to bypass the automatic context request normally
1467 performed by nbd_opt_go(3).
1468 The NBD protocol allows a client to decide how many queries to ask the
1470 server. This function takes an explicit list of queries; to instead re‐
1471 use an implicit list, see nbd_opt_set_meta_context(3). Since this func‐
1472 tion is primarily designed for testing servers, libnbd does not prevent
1473 the use of this function on an empty list or when nbd_set_re‐
1474 quest_structured_replies(3) has disabled structured replies, in order
1475 to see how a server behaves.
1476 The "context" function is called once per server reply, with any
1478 "user_data" passed to this function, and with "name" supplied by the
1479 server. Additionally, each server name will remain visible through
1480 nbd_can_meta_context(3) until the next attempt at nbd_set_ex‐
1481 port_name(3) or nbd_opt_set_meta_context(3), as well as nbd_opt_go(3)
1482 or nbd_opt_info(3) that trigger an automatic meta context request. Re‐
1483 member that it is not safe to call any "nbd_*" APIs from within the
1484 context of the callback function. At present, the return value of the
1485 callback is ignored, although a return of -1 should be avoided.
1486 For convenience, when this function succeeds, it returns the number of
1488 replies returned by the server.
1489 Not all servers understand this request, and even when it is under‐
1491 stood, the server might intentionally send an empty list because it
1492 does not support the requested context, or may encounter a failure af‐
1493 ter delivering partial results. Thus, this function may succeed even
1494 when no contexts are reported, or may fail but have a non-empty list.
1495 val add_meta_context : t -> string -> unit
1499 NBD.add_meta_context t name
1502 ask server to negotiate metadata context
1504 During connection libnbd can negotiate zero or more metadata contexts
1506 with the server. Metadata contexts are features (such as "base:alloca‐
1507 tion") which describe information returned by the nbd_block_sta‐
1508 tus_64(3) command (for "base:allocation" this is whether blocks of data
1509 are allocated, zero or sparse).
1510 This call adds one metadata context to the list to be negotiated. You
1512 can call it as many times as needed. The list is initially empty when
1513 the handle is created; you can check the contents of the list with
1514 nbd_get_nr_meta_contexts(3) and nbd_get_meta_context(3), or clear it
1515 with nbd_clear_meta_contexts(3).
1516 The NBD protocol limits meta context names to 4096 bytes, but servers
1518 may not support the full length. The encoding of meta context names is
1519 always UTF-8.
1520 Not all servers support all metadata contexts. To learn if a context
1522 was actually negotiated, call nbd_can_meta_context(3) after connecting.
1523 The single parameter is the name of the metadata context, for example
1525 "LIBNBD_CONTEXT_BASE_ALLOCATION". <libnbd.h> includes defined con‐
1526 stants beginning with "LIBNBD_CONTEXT_" for some well-known contexts,
1527 but you are free to pass in other contexts.
1528 Other metadata contexts are server-specific, but include
1530 "qemu:dirty-bitmap:..." and "qemu:allocation-depth" for qemu-nbd (see
1531 qemu-nbd *-B* and *-A* options).
1532 val get_nr_meta_contexts : t -> int
1536 NBD.get_nr_meta_contexts t
1539 return the current number of requested meta contexts
1541 During connection libnbd can negotiate zero or more metadata contexts
1543 with the server. Metadata contexts are features (such as "base:alloca‐
1544 tion") which describe information returned by the nbd_block_sta‐
1545 tus_64(3) command (for "base:allocation" this is whether blocks of data
1546 are allocated, zero or sparse).
1547 This command returns how many meta contexts have been added to the list
1549 to request from the server via nbd_add_meta_context(3). The server is
1550 not obligated to honor all of the requests; to see what it actually
1551 supports, see nbd_can_meta_context(3).
1552 val get_meta_context : t -> int -> string
1556 NBD.get_meta_context t i
1559 return the i'th meta context request
1561 During connection libnbd can negotiate zero or more metadata contexts
1563 with the server. Metadata contexts are features (such as "base:alloca‐
1564 tion") which describe information returned by the nbd_block_sta‐
1565 tus_64(3) command (for "base:allocation" this is whether blocks of data
1566 are allocated, zero or sparse).
1567 This command returns the i'th meta context request, as added by
1569 nbd_add_meta_context(3), and bounded by nbd_get_nr_meta_contexts(3).
1570 val clear_meta_contexts : t -> unit
1574 NBD.clear_meta_contexts t
1577 reset the list of requested meta contexts
1579 During connection libnbd can negotiate zero or more metadata contexts
1581 with the server. Metadata contexts are features (such as "base:alloca‐
1582 tion") which describe information returned by the nbd_block_sta‐
1583 tus_64(3) command (for "base:allocation" this is whether blocks of data
1584 are allocated, zero or sparse).
1585 This command resets the list of meta contexts to request back to an
1587 empty list, for re-population by further use of nbd_add_meta_con‐
1588 text(3). It is primarily useful when option negotiation mode is se‐
1589 lected (see nbd_set_opt_mode(3)), for altering the list of attempted
1590 contexts between subsequent export queries.
1591 val set_uri_allow_transports : t -> ALLOW_TRANSPORT.t list -> unit
1595 NBD.set_uri_allow_transports t mask
1598 set the allowed transports in NBD URIs
1600 Set which transports are allowed to appear in NBD URIs. The default is
1602 to allow any transport.
1603 The "mask" parameter may contain any of the following flags ORed to‐
1605 gether:
1606 "LIBNBD_ALLOW_TRANSPORT_TCP" = 0x1 "LIBNBD_ALLOW_TRANSPORT_UNIX" = 0x2
1608 "LIBNBD_ALLOW_TRANSPORT_VSOCK" = 0x4
1609 For convenience, the constant "LIBNBD_ALLOW_TRANSPORT_MASK" is avail‐
1611 able to describe all transports recognized by this build of libnbd. A
1612 future version of the library may add new flags.
1613 val set_uri_allow_tls : t -> TLS.t -> unit
1617 NBD.set_uri_allow_tls t tls
1620 set the allowed TLS settings in NBD URIs
1622 Set which TLS settings are allowed to appear in NBD URIs. The default
1624 is to allow either non-TLS or TLS URIs.
1625 The "tls" parameter can be:
1627 "LIBNBD_TLS_DISABLE" TLS URIs are not permitted, ie. a URI such as
1629 "nbds://..." will be rejected.
1630 "LIBNBD_TLS_ALLOW" This is the default. TLS may be used or not, depend‐
1632 ing on whether the URI uses "nbds" or "nbd".
1633 "LIBNBD_TLS_REQUIRE" TLS URIs are required. All URIs must use "nbds".
1635 val set_uri_allow_local_file : t -> bool -> unit
1639 NBD.set_uri_allow_local_file t allow
1642 set the allowed transports in NBD URIs
1644 Allow NBD URIs to reference local files. This is *disabled* by default.
1646 Currently this setting only controls whether the "tls-psk-file" parame‐
1648 ter in NBD URIs is allowed.
1649 val connect_uri : t -> string -> unit
1653 NBD.connect_uri t uri
1656 connect to NBD URI
1658 Connect (synchronously) to an NBD server and export by specifying the
1660 NBD URI. This call parses the URI and calls nbd_set_export_name(3) and
1661 nbd_set_tls(3) and other calls as needed, followed by nbd_con‐
1662 nect_tcp(3), nbd_connect_unix(3) or nbd_connect_vsock(3).
1663 This call returns when the connection has been made. By default, this
1665 proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can
1666 be used for manual control over option negotiation performed before
1667 transmission phase.
1668 Example URIs supported "nbd://example.com" Connect over TCP, unen‐
1670 crypted, to "example.com" port 10809.
1671 "nbds://example.com" Connect over TCP with TLS, to "example.com" port
1673 10809. If the server does not support TLS then this will fail.
1674 "nbd+unix:///foo?socket=/tmp/nbd.sock" Connect over the Unix domain
1676 socket /tmp/nbd.sock to an NBD server running locally. The export name
1677 is set to "foo" (note without any leading "/" character).
1678 "nbds+unix://alice@/?socket=/tmp/nbd.sock&tls-certificat es=certs" Con‐
1680 nect over a Unix domain socket, enabling TLS and setting the path to a
1681 directory containing certificates and keys.
1682 "nbd+vsock:///" In this scenario libnbd is running in a virtual ma‐
1684 chine. Connect over "AF_VSOCK" to an NBD server running on the hypervi‐
1685 sor.
1686 Supported URI formats The following schemes are supported in the cur‐
1688 rent version of libnbd:
1689 "nbd:" Connect over TCP without using TLS.
1691 "nbds:" Connect over TCP. TLS is required and the connection will fail
1693 if the server does not support TLS.
1694 "nbd+unix:" "nbds+unix:" Connect over a Unix domain socket, without or
1696 with TLS respectively. The "socket" parameter is required.
1697 "nbd+vsock:" "nbds+vsock:" Connect over the "AF_VSOCK" transport, with‐
1699 out or with TLS respectively. You can use nbd_supports_vsock(3) to see
1700 if this build of libnbd supports "AF_VSOCK".
1701 The authority part of the URI (" username@ servername :port ") is
1703 parsed depending on the transport. For TCP it specifies the server to
1704 connect to and optional port number. For "+unix" it should not be
1705 present. For "+vsock" the server name is the numeric CID (eg. 2 to con‐
1706 nect to the host), and the optional port number may be present. If the
1707 "username" is present it is used for TLS authentication.
1708 For all transports, an export name may be present, parsed in accordance
1710 with the NBD URI specification.
1711 Finally the query part of the URI can contain:
1713 socket=SOCKET Specifies the Unix domain socket to connect on. Must be
1715 present for the "+unix" transport and must not be present for the other
1716 transports.
1717 tls-certificates=DIR Set the certificates directory. See
1719 nbd_set_tls_certificates(3). Note this is not allowed by default - see
1720 next section.
1721 tls-psk-file=PSKFILE Set the PSK file. See nbd_set_tls_psk_file(3).
1723 Note this is not allowed by default - see next section.
1724 Disable URI features For security reasons you might want to disable
1726 certain URI features. Pre-filtering URIs is error-prone and should not
1727 be attempted. Instead use the libnbd APIs below to control what can ap‐
1728 pear in URIs. Note you must call these functions on the same handle be‐
1729 fore calling nbd_connect_uri(3) or nbd_aio_connect_uri(3).
1730 TCP, Unix domain socket or "AF_VSOCK" transports Default: all allowed
1732 To select which transports are allowed call nbd_set_uri_allow_trans‐
1734 ports(3).
1735 TLS Default: both non-TLS and TLS connections allowed
1737 To force TLS off or on in URIs call nbd_set_uri_allow_tls(3).
1739 Connect to Unix domain socket in the local filesystem Default: allowed
1741 To prevent this you must disable the "+unix" transport using
1743 nbd_set_uri_allow_transports(3).
1744 Read from local files Default: denied
1746 To allow URIs to contain references to local files (eg. for parameters
1748 like "tls-psk-file") call nbd_set_uri_allow_local_file(3).
1749 Overriding the export name It is possible to override the export name
1751 portion of a URI by using nbd_set_opt_mode(3) to enable option mode,
1752 then using nbd_set_export_name(3) and nbd_opt_go(3) as part of subse‐
1753 quent negotiation.
1754 Optional features This call will fail if libnbd was not compiled with
1756 libxml2; you can test whether this is the case with nbd_sup‐
1757 ports_uri(3).
1758 Support for URIs that require TLS will fail if libnbd was not compiled
1760 with gnutls; you can test whether this is the case with nbd_sup‐
1761 ports_tls(3).
1762 Constructing a URI from an existing connection See nbd_get_uri(3).
1764 val connect_unix : t -> string -> unit
1768 NBD.connect_unix t unixsocket
1771 connect to NBD server over a Unix domain socket
1773 Connect (synchronously) over the named Unix domain socket ("unix‐
1775 socket") to an NBD server running on the same machine.
1776 This call returns when the connection has been made. By default, this
1778 proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can
1779 be used for manual control over option negotiation performed before
1780 transmission phase.
1781 val connect_vsock : t -> int64 -> int64 -> unit
1785 NBD.connect_vsock t cid port
1788 connect to NBD server over AF_VSOCK protocol
1790 Connect (synchronously) over the "AF_VSOCK" protocol from a virtual ma‐
1792 chine to an NBD server, usually running on the host. The "cid" and
1793 "port" parameters specify the server address. Usually "cid" should be 2
1794 (to connect to the host), and "port" might be 10809 or another port
1795 number assigned to you by the host administrator.
1796 Not all systems support "AF_VSOCK"; to determine if libnbd was built on
1798 a system with vsock support, see nbd_supports_vsock(3).
1799 This call returns when the connection has been made. By default, this
1801 proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can
1802 be used for manual control over option negotiation performed before
1803 transmission phase.
1804 val connect_tcp : t -> string -> string -> unit
1808 NBD.connect_tcp t hostname port
1811 connect to NBD server over a TCP port
1813 Connect (synchronously) to the NBD server listening on "hostname:port".
1815 The "port" may be a port name such as "nbd", or it may be a port number
1816 as a string such as "10809".
1817 This call returns when the connection has been made. By default, this
1819 proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can
1820 be used for manual control over option negotiation performed before
1821 transmission phase.
1822 val connect_socket : t -> Unix.file_descr -> unit
1826 NBD.connect_socket t sock
1829 connect directly to a connected socket
1831 Pass a connected socket "sock" through which libnbd will talk to the
1833 NBD server.
1834 The caller is responsible for creating and connecting this socket by
1836 some method, before passing it to libnbd.
1837 If this call returns without error then socket ownership is passed to
1839 libnbd. Libnbd will close the socket when the handle is closed. The
1840 caller must not use the socket in any way.
1841 This call returns when the connection has been made. By default, this
1843 proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can
1844 be used for manual control over option negotiation performed before
1845 transmission phase.
1846 val connect_command : t -> string list -> unit
1850 NBD.connect_command t argv
1853 connect to NBD server command
1855 Run the command as a subprocess and connect to it over stdin/stdout.
1857 This is for use with NBD servers which can behave like inetd clients,
1858 such as nbdkit(1) using the *-s*/*--single* flag, and nbd-server(1)
1859 with port number set to 0.
1860 To run qemu-nbd(1), use nbd_connect_systemd_socket_activation(3) in‐
1862 stead.
1863 Subprocess Libnbd will fork the "argv" command and pass the NBD socket
1865 to it using file descriptors 0 and 1 (stdin/stdout):
1866 ┌─────────┬─────────┐ ┌────────────────┐ │ program │ libnbd │ │
1868 NBD server │ │ │ │ │ (argv) │ │ │
1869 socket ╍╍╍╍╍╍╍╍▶ stdin/stdout │ └─────────┴─────────┘
1870 └────────────────┘
1871 When the NBD handle is closed the server subprocess is killed.
1873 This call returns when the connection has been made. By default, this
1875 proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can
1876 be used for manual control over option negotiation performed before
1877 transmission phase.
1878 val connect_systemd_socket_activation : t -> string list -> unit
1882 NBD.connect_systemd_socket_activation t argv
1885 connect using systemd socket activation
1887 Run the command as a subprocess and connect to it using systemd socket
1889 activation.
1890 This is especially useful for running qemu-nbd(1) as a subprocess of
1892 libnbd, for example to use it to open qcow2 files.
1893 To run nbdkit as a subprocess, this function can be used, or nbd_con‐
1895 nect_command(3).
1896 To run nbd-server(1) as a subprocess, this function cannot be used, you
1898 must use nbd_connect_command(3).
1899 Socket activation Libnbd will fork the "argv" command and pass an NBD
1901 socket to it using special "LISTEN_*" environment variables (as defined
1902 by the systemd socket activation protocol).
1903 ┌─────────┬─────────┐ ┌───────────────┐ │ program │ libnbd │ │
1905 qemu-nbd or │ │ │ │ │ other server │ │ │
1906 socket ╍╍╍╍╍╍╍╍▶ │ └─────────┴─────────┘
1907 └───────────────┘
1908 When the NBD handle is closed the server subprocess is killed.
1910 Socket name The socket activation protocol lets you optionally give the
1912 socket a name. If used, the name is passed to the NBD server using the
1913 "LISTEN_FDNAMES" environment variable. To provide a socket name, call
1914 nbd_set_socket_activation_name(3) before calling the connect function.
1915 This call returns when the connection has been made. By default, this
1917 proceeds all the way to transmission phase, but nbd_set_opt_mode(3) can
1918 be used for manual control over option negotiation performed before
1919 transmission phase.
1920 val set_socket_activation_name : t -> string -> unit
1924 NBD.set_socket_activation_name t socket_name
1927 set the socket activation name
1929 When running an NBD server using nbd_connect_systemd_socket_activa‐
1931 tion(3) you can optionally name the socket. Call this function before
1932 connecting to the server.
1933 Some servers such as qemu-storage-daemon(1) can use this information to
1935 associate the socket with a name used on the command line, but most
1936 servers will ignore it. The name is passed through the "LISTEN_FDNAMES"
1937 environment variable.
1938 The parameter "socket_name" can be a short alphanumeric string. If it
1940 is set to the empty string (also the default when the handle is cre‐
1941 ated) then the name "unknown" will be seen by the server.
1942 val get_socket_activation_name : t -> string
1946 NBD.get_socket_activation_name t
1949 get the socket activation name
1951 Return the socket name used when you call nbd_connect_sys‐
1953 temd_socket_activation(3) on the same handle. By default this will re‐
1954 turn the empty string meaning that the server will see the name "un‐
1955 known".
1956 val is_read_only : t -> bool
1960 NBD.is_read_only t
1963 is the NBD export read-only?
1965 Returns true if the NBD export is read-only; writes and write-like op‐
1967 erations will fail.
1968 This call does not block, because it returns data that is saved in the
1970 handle from the NBD protocol handshake.
1971 val can_flush : t -> bool
1975 NBD.can_flush t
1978 does the server support the flush command?
1980 Returns true if the server supports the flush command (see
1982 nbd_flush(3), nbd_aio_flush(3)). Returns false if the server does not.
1983 This call does not block, because it returns data that is saved in the
1985 handle from the NBD protocol handshake.
1986 val can_fua : t -> bool
1990 NBD.can_fua t
1993 does the server support the FUA flag?
1995 Returns true if the server supports the FUA flag on certain commands
1997 (see nbd_pwrite(3)).
1998 This call does not block, because it returns data that is saved in the
2000 handle from the NBD protocol handshake.
2001 val is_rotational : t -> bool
2005 NBD.is_rotational t
2008 is the NBD disk rotational (like a disk)?
2010 Returns true if the disk exposed over NBD is rotational (like a tradi‐
2012 tional floppy or hard disk). Returns false if the disk has no penalty
2013 for random access (like an SSD or RAM disk).
2014 This call does not block, because it returns data that is saved in the
2016 handle from the NBD protocol handshake.
2017 val can_trim : t -> bool
2021 NBD.can_trim t
2024 does the server support the trim command?
2026 Returns true if the server supports the trim command (see nbd_trim(3),
2028 nbd_aio_trim(3)). Returns false if the server does not.
2029 This call does not block, because it returns data that is saved in the
2031 handle from the NBD protocol handshake.
2032 val can_zero : t -> bool
2036 NBD.can_zero t
2039 does the server support the zero command?
2041 Returns true if the server supports the zero command (see nbd_zero(3),
2043 nbd_aio_zero(3)). Returns false if the server does not.
2044 This call does not block, because it returns data that is saved in the
2046 handle from the NBD protocol handshake.
2047 val can_fast_zero : t -> bool
2051 NBD.can_fast_zero t
2054 does the server support the fast zero flag?
2056 Returns true if the server supports the use of the
2058 "LIBNBD_CMD_FLAG_FAST_ZERO" flag to the zero command (see nbd_zero(3),
2059 nbd_aio_zero(3)). Returns false if the server does not.
2060 This call does not block, because it returns data that is saved in the
2062 handle from the NBD protocol handshake.
2063 val can_block_status_payload : t -> bool
2067 NBD.can_block_status_payload t
2070 does the server support the block status payload flag?
2072 Returns true if the server supports the use of the
2074 "LIBNBD_CMD_FLAG_PAYLOAD_LEN" flag to allow filtering of the block sta‐
2075 tus command (see nbd_block_status_filter(3)). Returns false if the
2076 server does not. Note that this will never return true if nbd_get_ex‐
2077 tended_headers_negotiated(3) is false.
2078 This call does not block, because it returns data that is saved in the
2080 handle from the NBD protocol handshake.
2081 val can_df : t -> bool
2085 NBD.can_df t
2088 does the server support the don't fragment flag to pread?
2090 Returns true if the server supports structured reads with an ability to
2092 request a non-fragmented read (see nbd_pread_structured(3),
2093 nbd_aio_pread_structured(3)). Returns false if the server either lacks
2094 structured reads or if it does not support a non-fragmented read re‐
2095 quest.
2096 This call does not block, because it returns data that is saved in the
2098 handle from the NBD protocol handshake.
2099 val can_multi_conn : t -> bool
2103 NBD.can_multi_conn t
2106 does the server support multi-conn?
2108 Returns true if the server supports multi-conn. Returns false if the
2110 server does not.
2111 It is not safe to open multiple handles connecting to the same server
2113 if you will write to the server and the server does not advertise
2114 multi-conn support. The safe way to check for this is to open one con‐
2115 nection, check this flag is true, then open further connections as re‐
2116 quired.
2117 This call does not block, because it returns data that is saved in the
2119 handle from the NBD protocol handshake.
2120 val can_cache : t -> bool
2124 NBD.can_cache t
2127 does the server support the cache command?
2129 Returns true if the server supports the cache command (see
2131 nbd_cache(3), nbd_aio_cache(3)). Returns false if the server does not.
2132 This call does not block, because it returns data that is saved in the
2134 handle from the NBD protocol handshake.
2135 val can_meta_context : t -> string -> bool
2139 NBD.can_meta_context t metacontext
2142 does the server support a specific meta context?
2144 Returns true if the server supports the given meta context (see
2146 nbd_add_meta_context(3)). Returns false if the server does not. It is
2147 possible for this command to fail if meta contexts were requested but
2148 there is a missing or failed attempt at NBD_OPT_SET_META_CONTEXT during
2149 option negotiation.
2150 If the server supports block status filtering (see nbd_can_block_sta‐
2152 tus_payload(3), this function must return true for any filter name
2153 passed to nbd_block_status_filter(3).
2154 The single parameter is the name of the metadata context, for example
2156 "LIBNBD_CONTEXT_BASE_ALLOCATION". <libnbd.h> includes defined con‐
2157 stants for well-known namespace contexts beginning with "LIBNBD_CON‐
2158 TEXT_", but you are free to pass in other contexts.
2159 This call does not block, because it returns data that is saved in the
2161 handle from the NBD protocol handshake.
2162 val get_protocol : t -> string
2166 NBD.get_protocol t
2169 return the NBD protocol variant
2171 Return the NBD protocol variant in use on the connection. At the moment
2173 this returns one of the strings "oldstyle", "newstyle" or "new‐
2174 style-fixed". Other strings might be returned in the future. Most mod‐
2175 ern NBD servers use "newstyle-fixed".
2176 This call does not block, because it returns data that is saved in the
2178 handle from the NBD protocol handshake.
2179 val get_size : t -> int64
2183 NBD.get_size t
2186 return the export size
2188 Returns the size in bytes of the NBD export.
2190 Note that this call fails with "EOVERFLOW" for an unlikely server that
2192 advertises a size which cannot fit in a 64-bit signed integer.
2193 This call does not block, because it returns data that is saved in the
2195 handle from the NBD protocol handshake.
2196 val get_block_size : t -> SIZE.t -> int64
2200 NBD.get_block_size t size_type
2203 return a specific server block size constraint
2205 Returns a specific size constraint advertised by the server, if any. If
2207 the return is zero, the server did not advertise a constraint.
2208 "size_type" must be one of the following constraints:
2209 "LIBNBD_SIZE_MINIMUM" = 0 If non-zero, this will be a power of 2 be‐
2211 tween 1 and 64k; any client request that is not aligned in length or
2212 offset to this size is likely to fail with "EINVAL". The image size
2213 will generally also be a multiple of this value (if not, the final few
2214 bytes are inaccessible while obeying alignment constraints). If zero,
2215 it is safest to assume a minimum block size of 512, although many
2216 servers support a minimum block size of 1. If the server provides a
2217 constraint, then libnbd defaults to honoring that constraint
2218 client-side unless "LIBNBD_STRICT_ALIGN" is cleared in
2219 nbd_set_strict_mode(3).
2220 "LIBNBD_SIZE_PREFERRED" = 1 If non-zero, this is a power of 2 repre‐
2222 senting the preferred size for efficient I/O. Smaller requests may in‐
2223 cur overhead such as read-modify-write cycles that will not be present
2224 when using I/O that is a multiple of this value. This value may be
2225 larger than the size of the export. If zero, using 4k as a preferred
2226 block size tends to give decent performance.
2227 "LIBNBD_SIZE_MAXIMUM" = 2 If non-zero, this represents the maximum
2229 length that the server is willing to handle during nbd_pread(3) or
2230 nbd_pwrite(3). Other functions like nbd_zero(3) may still be able to
2231 use larger sizes. Note that this function returns what the server ad‐
2232 vertised, but libnbd itself imposes a maximum of 64M. If zero, some NBD
2233 servers will abruptly disconnect if a transaction involves more than
2234 32M.
2235 "LIBNBD_SIZE_PAYLOAD" = 3 This value is not advertised by the server,
2237 but rather represents the maximum outgoing payload size for a given
2238 connection that libnbd will enforce unless "LIBNBD_STRICT_PAYLOAD" is
2239 cleared in nbd_set_strict_mode(3). It is always non-zero: never smaller
2240 than 1M, never larger than 64M, and matches "LIBNBD_SIZE_MAXIMUM" when
2241 possible.
2242 Future NBD extensions may result in additional "size_type" values. Note
2244 that by default, libnbd requests all available block sizes, but that a
2245 server may differ in what sizes it chooses to report if nbd_set_re‐
2246 quest_block_size(3) alters whether the client requests sizes.
2247 This call does not block, because it returns data that is saved in the
2249 handle from the NBD protocol handshake.
2250 val pread : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 -> unit
2254 NBD.pread t ?flags buf offset
2257 read from the NBD server
2259 Issue a read command to the NBD server for the range starting at "off‐
2261 set" and ending at "offset" + "count" - 1. NBD can only read all or
2262 nothing using this call. The call returns when the data has been read
2263 fully into "buf" or there is an error. See also nbd_pread_struc‐
2264 tured(3), if finer visibility is required into the server's replies, or
2265 if you want to use "LIBNBD_CMD_FLAG_DF".
2266 Note that libnbd currently enforces a maximum read buffer of 64MiB,
2268 even if the server would permit a larger buffer in a single transac‐
2269 tion; attempts to exceed this will result in an "ERANGE" error. The
2270 server may enforce a smaller limit, which can be learned with
2271 nbd_get_block_size(3).
2272 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
2274 tocol extensions).
2275 Note that if this command fails, and nbd_get_pread_initialize(3) re‐
2277 turns true, then libnbd sanitized "buf", but it is unspecified whether
2278 the contents of "buf" will read as zero or as partial results from the
2279 server. If nbd_get_pread_initialize(3) returns false, then libnbd did
2280 not sanitize "buf", and the contents are undefined on failure.
2281 By default, libnbd will reject attempts to use this function with pa‐
2283 rameters that are likely to result in server failure, such as request‐
2284 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2285 used to alter which scenarios should await a server reply rather than
2286 failing fast.
2287 val pread_structured : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 ->
2291 (bytes -> int64 -> int -> int Stdlib.ref -> int) -> unit
2292 NBD.pread_structured t ?flags buf offset chunk
2295 read from the NBD server
2297 Issue a read command to the NBD server for the range starting at "off‐
2299 set" and ending at "offset" + "count" - 1. The server's response may be
2300 subdivided into chunks which may arrive out of order before reassembly
2301 into the original buffer; the "chunk" callback is used for notification
2302 after each chunk arrives, and may perform additional sanity checking on
2303 the server's reply. The callback cannot call "nbd_*" APIs on the same
2304 handle since it holds the handle lock and will cause a deadlock. If the
2305 callback returns -1, and no earlier error has been detected, then the
2306 overall read command will fail with any non-zero value stored into the
2307 callback's "error" parameter (with a default of "EPROTO"); but any fur‐
2308 ther chunks will still invoke the callback.
2309 The "chunk" function is called once per chunk of data received, with
2311 the "user_data" passed to this function. The "subbuf" and "count" pa‐
2312 rameters represent the subset of the original buffer which has just
2313 been populated by results from the server (in C, "subbuf" always points
2314 within the original "buf"; but this guarantee may not extend to other
2315 language bindings). The "offset" parameter represents the absolute off‐
2316 set at which "subbuf" begins within the image (note that this is not
2317 the relative offset of "subbuf" within the original buffer "buf").
2318 Changes to "error" on output are ignored unless the callback fails. The
2319 input meaning of the "error" parameter is controlled by the "status"
2320 parameter, which is one of
2321 "LIBNBD_READ_DATA" = 1 "subbuf" was populated with "count" bytes of
2323 data. On input, "error" contains the errno value of any earlier de‐
2324 tected error, or zero.
2325 "LIBNBD_READ_HOLE" = 2 "subbuf" represents a hole, and contains "count"
2327 NUL bytes. On input, "error" contains the errno value of any earlier
2328 detected error, or zero.
2329 "LIBNBD_READ_ERROR" = 3 "count" is 0, so "subbuf" is unusable. On in‐
2331 put, "error" contains the errno value reported by the server as occur‐
2332 ring while reading that "offset", regardless if any earlier error has
2333 been detected.
2334 Future NBD extensions may permit other values for "status", but those
2336 will not be returned to a client that has not opted in to requesting
2337 such extensions. If the server is non-compliant, it is possible for the
2338 "chunk" function to be called more times than you expect or with
2339 "count" 0 for "LIBNBD_READ_DATA" or "LIBNBD_READ_HOLE". It is also pos‐
2340 sible that the "chunk" function is not called at all (in particular,
2341 "LIBNBD_READ_ERROR" is used only when an error is associated with a
2342 particular offset, and not when the server reports a generic error),
2343 but you are guaranteed that the callback was called at least once if
2344 the overall read succeeds. Libnbd does not validate that the server
2345 obeyed the requirement that a read call must not have overlapping
2346 chunks and must not succeed without enough chunks to cover the entire
2347 request.
2348 Note that libnbd currently enforces a maximum read buffer of 64MiB,
2350 even if the server would permit a larger buffer in a single transac‐
2351 tion; attempts to exceed this will result in an "ERANGE" error. The
2352 server may enforce a smaller limit, which can be learned with
2353 nbd_get_block_size(3).
2354 The "flags" parameter may be 0 for no flags, or may contain
2356 "LIBNBD_CMD_FLAG_DF" meaning that the server should not reply with more
2357 than one fragment (if that is supported - some servers cannot do this,
2358 see nbd_can_df(3)). Libnbd does not validate that the server actually
2359 obeys the flag.
2360 Note that if this command fails, and nbd_get_pread_initialize(3) re‐
2362 turns true, then libnbd sanitized "buf", but it is unspecified whether
2363 the contents of "buf" will read as zero or as partial results from the
2364 server. If nbd_get_pread_initialize(3) returns false, then libnbd did
2365 not sanitize "buf", and the contents are undefined on failure.
2366 By default, libnbd will reject attempts to use this function with pa‐
2368 rameters that are likely to result in server failure, such as request‐
2369 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2370 used to alter which scenarios should await a server reply rather than
2371 failing fast.
2372 val pwrite : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 -> unit
2376 NBD.pwrite t ?flags buf offset
2379 write to the NBD server
2381 Issue a write command to the NBD server, writing the data in "buf" to
2383 the range starting at "offset" and ending at "offset" + "count" - 1.
2384 NBD can only write all or nothing using this call. The call returns
2385 when the command has been acknowledged by the server, or there is an
2386 error. Note this will generally return an error if nbd_is_read_only(3)
2387 is true.
2388 Note that libnbd defaults to enforcing a maximum write buffer of the
2390 lesser of 64MiB or any maximum payload size advertised by the server;
2391 attempts to exceed this will generally result in a client-side "ERANGE"
2392 error, rather than a server-side disconnection. The actual limit can be
2393 learned with nbd_get_block_size(3).
2394 The "flags" parameter may be 0 for no flags, or may contain
2396 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
2397 the data has been committed to permanent storage (if that is supported
2398 - some servers cannot do this, see nbd_can_fua(3)). For convenience,
2399 unless nbd_set_strict_flags(3) was used to disable
2400 "LIBNBD_STRICT_AUTO_FLAG", libnbd ignores the presence or absence of
2401 the flag "LIBNBD_CMD_FLAG_PAYLOAD_LEN" in "flags", while correctly us‐
2402 ing the flag over the wire according to whether extended headers were
2403 negotiated.
2404 By default, libnbd will reject attempts to use this function with pa‐
2406 rameters that are likely to result in server failure, such as request‐
2407 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2408 used to alter which scenarios should await a server reply rather than
2409 failing fast.
2410 val shutdown : ?flags:SHUTDOWN.t list -> t -> unit
2414 NBD.shutdown t ?flags
2417 disconnect from the NBD server
2419 Issue the disconnect command to the NBD server. This is a nice way to
2421 tell the server we are going away, but from the client's point of view
2422 has no advantage over abruptly closing the connection (see
2423 nbd_close(3)).
2424 This function works whether or not the handle is ready for transmission
2426 of commands. If more fine-grained control is needed, see
2427 nbd_aio_opt_abort(3) and nbd_aio_disconnect(3).
2428 The "flags" argument is a bitmask, including zero or more of the fol‐
2430 lowing shutdown flags:
2431 "LIBNBD_SHUTDOWN_ABANDON_PENDING" = 0x10000 If there are any pending
2433 requests which have not yet been sent to the server (see
2434 nbd_aio_in_flight(3)), abandon them without sending them to the server,
2435 rather than the usual practice of issuing those commands before inform‐
2436 ing the server of the intent to disconnect.
2437 For convenience, the constant "LIBNBD_SHUTDOWN_MASK" is available to
2439 describe all shutdown flags recognized by this build of libnbd. A fu‐
2440 ture version of the library may add new flags.
2441 val flush : ?flags:CMD_FLAG.t list -> t -> unit
2445 NBD.flush t ?flags
2448 send flush command to the NBD server
2450 Issue the flush command to the NBD server. The function should return
2452 when all write commands which have completed have been committed to
2453 permanent storage on the server. Note this will generally return an er‐
2454 ror if nbd_can_flush(3) is false.
2455 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
2457 tocol extensions).
2458 By default, libnbd will reject attempts to use this function with pa‐
2460 rameters that are likely to result in server failure, such as request‐
2461 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2462 used to alter which scenarios should await a server reply rather than
2463 failing fast.
2464 val trim : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
2468 NBD.trim t ?flags count offset
2471 send trim command to the NBD server
2473 Issue a trim command to the NBD server, which if supported by the
2475 server causes a hole to be punched in the backing store starting at
2476 "offset" and ending at "offset" + "count" - 1. The call returns when
2477 the command has been acknowledged by the server, or there is an error.
2478 Note this will generally return an error if nbd_can_trim(3) is false or
2479 nbd_is_read_only(3) is true.
2480 Note that not all servers can support a "count" of 4GiB or larger;
2482 nbd_get_extended_headers_negotiated(3) indicates which servers will
2483 parse a request larger than 32 bits. The NBD protocol does not yet have
2484 a way for a client to learn if the server will enforce an even smaller
2485 maximum trim size, although a future extension may add a constraint
2486 visible in nbd_get_block_size(3).
2487 The "flags" parameter may be 0 for no flags, or may contain
2489 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
2490 the data has been committed to permanent storage (if that is supported
2491 - some servers cannot do this, see nbd_can_fua(3)).
2492 By default, libnbd will reject attempts to use this function with pa‐
2494 rameters that are likely to result in server failure, such as request‐
2495 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2496 used to alter which scenarios should await a server reply rather than
2497 failing fast.
2498 val cache : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
2502 NBD.cache t ?flags count offset
2505 send cache (prefetch) command to the NBD server
2507 Issue the cache (prefetch) command to the NBD server, which if sup‐
2509 ported by the server causes data to be prefetched into faster storage
2510 by the server, speeding up a subsequent nbd_pread(3) call. The server
2511 can also silently ignore this command. Note this will generally return
2512 an error if nbd_can_cache(3) is false.
2513 Note that not all servers can support a "count" of 4GiB or larger;
2515 nbd_get_extended_headers_negotiated(3) indicates which servers will
2516 parse a request larger than 32 bits. The NBD protocol does not yet have
2517 a way for a client to learn if the server will enforce an even smaller
2518 maximum cache size, although a future extension may add a constraint
2519 visible in nbd_get_block_size(3).
2520 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
2522 tocol extensions).
2523 By default, libnbd will reject attempts to use this function with pa‐
2525 rameters that are likely to result in server failure, such as request‐
2526 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2527 used to alter which scenarios should await a server reply rather than
2528 failing fast.
2529 val zero : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
2533 NBD.zero t ?flags count offset
2536 send write zeroes command to the NBD server
2538 Issue a write zeroes command to the NBD server, which if supported by
2540 the server causes a zeroes to be written efficiently starting at "off‐
2541 set" and ending at "offset"
2542 -"count" - 1. The call returns when the command has been acknowledged
2544 by the server, or there is an error. Note this will generally return
2545 an error if nbd_can_zero(3) is false or nbd_is_read_only(3) is true.
2546 Note that not all servers can support a "count" of 4GiB or larger;
2548 nbd_get_extended_headers_negotiated(3) indicates which servers will
2549 parse a request larger than 32 bits. The NBD protocol does not yet have
2550 a way for a client to learn if the server will enforce an even smaller
2551 maximum zero size, although a future extension may add a constraint
2552 visible in nbd_get_block_size(3). Also, some servers may permit a
2553 larger zero request only when the "LIBNBD_CMD_FLAG_FAST_ZERO" is in
2554 use.
2555 The "flags" parameter may be 0 for no flags, or may contain
2557 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
2558 the data has been committed to permanent storage (if that is supported
2559 - some servers cannot do this, see nbd_can_fua(3)),
2560 "LIBNBD_CMD_FLAG_NO_HOLE" meaning that the server should favor writing
2561 actual allocated zeroes over punching a hole, and/or
2562 "LIBNBD_CMD_FLAG_FAST_ZERO" meaning that the server must fail quickly
2563 if writing zeroes is no faster than a normal write (if that is sup‐
2564 ported - some servers cannot do this, see nbd_can_fast_zero(3)).
2565 By default, libnbd will reject attempts to use this function with pa‐
2567 rameters that are likely to result in server failure, such as request‐
2568 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2569 used to alter which scenarios should await a server reply rather than
2570 failing fast.
2571 val block_status : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 ->
2575 (string -> int64 -> int64 array -> int Stdlib.ref -> int) -> unit
2576 NBD.block_status t ?flags count offset extent
2579 send block status command, with 32-bit callback
2581 Issue the block status command to the NBD server. If supported by the
2583 server, this causes metadata context information about blocks beginning
2584 from the specified offset to be returned. The "count" parameter is a
2585 hint: the server may choose to return less status, or the final block
2586 may extend beyond the requested range. If multiple contexts are sup‐
2587 ported, the number of blocks and cumulative length of those blocks need
2588 not be identical between contexts.
2589 Note that not all servers can support a "count" of 4GiB or larger;
2591 nbd_get_extended_headers_negotiated(3) indicates which servers will
2592 parse a request larger than 32 bits. The NBD protocol does not yet have
2593 a way for a client to learn if the server will enforce an even smaller
2594 maximum block status size, although a future extension may add a con‐
2595 straint visible in nbd_get_block_size(3). Furthermore, this function is
2596 inherently limited to 32-bit values. If the server replies with a
2597 larger extent, the length of that extent will be truncated to just be‐
2598 low 32 bits and any further extents from the server will be ignored. If
2599 the server replies with a status value larger than 32 bits (only possi‐
2600 ble when extended headers are in use), the callback function will be
2601 passed an "EOVERFLOW" error. To get the full extent information from a
2602 server that supports 64-bit extents, you must use nbd_block_sta‐
2603 tus_64(3).
2604 Depending on which metadata contexts were enabled before connecting
2606 (see nbd_add_meta_context(3)) and which are supported by the server
2607 (see nbd_can_meta_context(3)) this call returns information about ex‐
2608 tents by calling back to the "extent" function. The callback cannot
2609 call "nbd_*" APIs on the same handle since it holds the handle lock and
2610 will cause a deadlock. If the callback returns -1, and no earlier error
2611 has been detected, then the overall block status command will fail with
2612 any non-zero value stored into the callback's "error" parameter (with a
2613 default of "EPROTO"); but any further contexts will still invoke the
2614 callback.
2615 The "extent" function is called once per type of metadata available,
2617 with the "user_data" passed to this function. The "metacontext" parame‐
2618 ter is a string such as "base:allocation". The "entries" array is an
2619 array of pairs of integers with the first entry in each pair being the
2620 length (in bytes) of the block and the second entry being a sta‐
2621 tus/flags field which is specific to the metadata context. The number
2622 of pairs passed to the function is "nr_entries/2". The NBD protocol
2623 document in the section about "NBD_REPLY_TYPE_BLOCK_STATUS" describes
2624 the meaning of this array; for contexts known to libnbd, <libnbd.h>
2625 contains constants beginning with "LIBNBD_STATE_" that may help deci‐
2626 pher the values. On entry to the callback, the "error" parameter con‐
2627 tains the errno value of any previously detected error, but even if an
2628 earlier error was detected, the current "metacontext" and "entries" are
2629 valid.
2630 It is possible for the extent function to be called more times than you
2632 expect (if the server is buggy), so always check the "metacontext"
2633 field to ensure you are receiving the data you expect. It is also pos‐
2634 sible that the extent function is not called at all, even for metadata
2635 contexts that you requested. This indicates either that the server
2636 doesn't support the context or for some other reason cannot return the
2637 data.
2638 The "flags" parameter may be 0 for no flags, or may contain
2640 "LIBNBD_CMD_FLAG_REQ_ONE" meaning that the server should return only
2641 one extent per metadata context where that extent does not exceed
2642 "count" bytes; however, libnbd does not validate that the server obeyed
2643 the flag.
2644 By default, libnbd will reject attempts to use this function with pa‐
2646 rameters that are likely to result in server failure, such as request‐
2647 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2648 used to alter which scenarios should await a server reply rather than
2649 failing fast.
2650 val block_status_64 : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 ->
2654 (string -> int64 -> extent array -> int Stdlib.ref -> int) -> unit
2655 NBD.block_status_64 t ?flags count offset extent64
2658 send block status command, with 64-bit callback
2660 Issue the block status command to the NBD server. If supported by the
2662 server, this causes metadata context information about blocks beginning
2663 from the specified offset to be returned. The "count" parameter is a
2664 hint: the server may choose to return less status, or the final block
2665 may extend beyond the requested range. When multiple contexts are sup‐
2666 ported, the number of blocks and cumulative length of those blocks need
2667 not be identical between contexts; this command generally returns the
2668 status of all negotiated contexts, while some servers also support a
2669 filtered request (see nbd_can_block_status_payload(3), nbd_block_sta‐
2670 tus_filter(3)).
2671 Note that not all servers can support a "count" of 4GiB or larger;
2673 nbd_get_extended_headers_negotiated(3) indicates which servers will
2674 parse a request larger than 32 bits. The NBD protocol does not yet have
2675 a way for a client to learn if the server will enforce an even smaller
2676 maximum block status size, although a future extension may add a con‐
2677 straint visible in nbd_get_block_size(3).
2678 Depending on which metadata contexts were enabled before connecting
2680 (see nbd_add_meta_context(3)) and which are supported by the server
2681 (see nbd_can_meta_context(3)) this call returns information about ex‐
2682 tents by calling back to the "extent64" function. The callback cannot
2683 call "nbd_*" APIs on the same handle since it holds the handle lock and
2684 will cause a deadlock. If the callback returns -1, and no earlier error
2685 has been detected, then the overall block status command will fail with
2686 any non-zero value stored into the callback's "error" parameter (with a
2687 default of "EPROTO"); but any further contexts will still invoke the
2688 callback.
2689 The "extent64" function is called once per type of metadata available,
2691 with the "user_data" passed to this function. The "metacontext" parame‐
2692 ter is a string such as "base:allocation". The "entries" array is an
2693 array of nbd_extent structs, containing length (in bytes) of the block
2694 and a status/flags field which is specific to the metadata context. The
2695 number of array entries passed to the function is "nr_entries". The NBD
2696 protocol document in the section about "NBD_REPLY_TYPE_BLOCK_STATUS"
2697 describes the meaning of this array; for contexts known to libnbd,
2698 <libnbd.h> contains constants beginning with "LIBNBD_STATE_" that may
2699 help decipher the values. On entry to the callback, the "error" parame‐
2700 ter contains the errno value of any previously detected error.
2701 It is possible for the extent function to be called more times than you
2703 expect (if the server is buggy), so always check the "metacontext"
2704 field to ensure you are receiving the data you expect. It is also pos‐
2705 sible that the extent function is not called at all, even for metadata
2706 contexts that you requested. This indicates either that the server
2707 doesn't support the context or for some other reason cannot return the
2708 data.
2709 The "flags" parameter may be 0 for no flags, or may contain
2711 "LIBNBD_CMD_FLAG_REQ_ONE" meaning that the server should return only
2712 one extent per metadata context where that extent does not exceed
2713 "count" bytes; however, libnbd does not validate that the server obeyed
2714 the flag.
2715 By default, libnbd will reject attempts to use this function with pa‐
2717 rameters that are likely to result in server failure, such as request‐
2718 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2719 used to alter which scenarios should await a server reply rather than
2720 failing fast.
2721 val block_status_filter : ?flags:CMD_FLAG.t list -> t -> int64 -> int64
2725 -> string list -> (string -> int64 -> extent array -> int Stdlib.ref ->
2726 int) -> unit
2727 NBD.block_status_filter t ?flags count offset contexts extent64
2730 send filtered block status command, with 64-bit callback
2732 Issue a filtered block status command to the NBD server. If supported
2734 by the server (see nbd_can_block_status_payload(3)), this causes meta‐
2735 data context information about blocks beginning from the specified off‐
2736 set to be returned, and with the result limited to just the contexts
2737 specified in "filter". Note that all strings in "filter" must be sup‐
2738 ported by nbd_can_meta_context(3).
2739 All other parameters to this function have the same semantics as in
2741 nbd_block_status_64(3); except that for convenience, unless
2742 <nbd_set_strict_flags(3)> was used to disable
2743 "LIBNBD_STRICT_AUTO_FLAG", libnbd ignores the presence or absence of
2744 the flag "LIBNBD_CMD_FLAG_PAYLOAD_LEN" in "flags", while correctly us‐
2745 ing the flag over the wire.
2746 By default, libnbd will reject attempts to use this function with pa‐
2748 rameters that are likely to result in server failure, such as request‐
2749 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2750 used to alter which scenarios should await a server reply rather than
2751 failing fast.
2752 val poll : t -> int -> int
2756 NBD.poll t timeout
2759 poll the handle once
2761 This is a simple implementation of poll(2) which is used internally by
2763 synchronous API calls. On success, it returns 0 if the "timeout" (in
2764 milliseconds) occurs, or 1 if the poll completed and the state machine
2765 progressed. Set "timeout" to -1 to block indefinitely (but be careful
2766 that eventual action is actually expected - for example, if the connec‐
2767 tion is established but there are no commands in flight, using an infi‐
2768 nite timeout will permanently block).
2769 This function is mainly useful as an example of how you might integrate
2771 libnbd with your own main loop, rather than being intended as something
2772 you would use.
2773 val poll2 : t -> Unix.file_descr -> int -> int
2777 NBD.poll2 t fd timeout
2780 poll the handle once, with fd
2782 This is the same as nbd_poll(3), but an additional file descriptor pa‐
2784 rameter is passed. The additional fd is also polled (using "POLLIN").
2785 One use for this is to wait for an eventfd(2).
2786 val aio_connect : t -> Unix.sockaddr -> unit
2790 NBD.aio_connect t addr
2793 connect to the NBD server
2795 Begin connecting to the NBD server. The "addr" and "addrlen" parameters
2797 specify the address of the socket to connect to.
2798 You can check if the connection attempt is still underway by calling
2800 nbd_aio_is_connecting(3). If nbd_set_opt_mode(3) is enabled, the con‐
2801 nection is ready for manual option negotiation once nbd_aio_is_negoti‐
2802 ating(3) returns true; otherwise, the connection attempt will include
2803 the NBD handshake, and is ready for use once nbd_aio_is_ready(3) re‐
2804 turns true.
2805 val aio_connect_uri : t -> string -> unit
2809 NBD.aio_connect_uri t uri
2812 connect to an NBD URI
2814 Begin connecting to the NBD URI "uri". Parameters behave as documented
2816 in nbd_connect_uri(3).
2817 You can check if the connection attempt is still underway by calling
2819 nbd_aio_is_connecting(3). If nbd_set_opt_mode(3) is enabled, the con‐
2820 nection is ready for manual option negotiation once nbd_aio_is_negoti‐
2821 ating(3) returns true; otherwise, the connection attempt will include
2822 the NBD handshake, and is ready for use once nbd_aio_is_ready(3) re‐
2823 turns true.
2824 val aio_connect_unix : t -> string -> unit
2828 NBD.aio_connect_unix t unixsocket
2831 connect to the NBD server over a Unix domain socket
2833 Begin connecting to the NBD server over Unix domain socket ("unix‐
2835 socket"). Parameters behave as documented in nbd_connect_unix(3).
2836 You can check if the connection attempt is still underway by calling
2838 nbd_aio_is_connecting(3). If nbd_set_opt_mode(3) is enabled, the con‐
2839 nection is ready for manual option negotiation once nbd_aio_is_negoti‐
2840 ating(3) returns true; otherwise, the connection attempt will include
2841 the NBD handshake, and is ready for use once nbd_aio_is_ready(3) re‐
2842 turns true.
2843 val aio_connect_vsock : t -> int64 -> int64 -> unit
2847 NBD.aio_connect_vsock t cid port
2850 connect to the NBD server over AF_VSOCK socket
2852 Begin connecting to the NBD server over the "AF_VSOCK" protocol to the
2854 server "cid:port". Parameters behave as documented in nbd_con‐
2855 nect_vsock(3).
2856 You can check if the connection attempt is still underway by calling
2858 nbd_aio_is_connecting(3). If nbd_set_opt_mode(3) is enabled, the con‐
2859 nection is ready for manual option negotiation once nbd_aio_is_negoti‐
2860 ating(3) returns true; otherwise, the connection attempt will include
2861 the NBD handshake, and is ready for use once nbd_aio_is_ready(3) re‐
2862 turns true.
2863 val aio_connect_tcp : t -> string -> string -> unit
2867 NBD.aio_connect_tcp t hostname port
2870 connect to the NBD server over a TCP port
2872 Begin connecting to the NBD server listening on "hostname:port". Param‐
2874 eters behave as documented in nbd_connect_tcp(3).
2875 You can check if the connection attempt is still underway by calling
2877 nbd_aio_is_connecting(3). If nbd_set_opt_mode(3) is enabled, the con‐
2878 nection is ready for manual option negotiation once nbd_aio_is_negoti‐
2879 ating(3) returns true; otherwise, the connection attempt will include
2880 the NBD handshake, and is ready for use once nbd_aio_is_ready(3) re‐
2881 turns true.
2882 val aio_connect_socket : t -> Unix.file_descr -> unit
2886 NBD.aio_connect_socket t sock
2889 connect directly to a connected socket
2891 Begin connecting to the connected socket "fd". Parameters behave as
2893 documented in nbd_connect_socket(3).
2894 You can check if the connection attempt is still underway by calling
2896 nbd_aio_is_connecting(3). If nbd_set_opt_mode(3) is enabled, the con‐
2897 nection is ready for manual option negotiation once nbd_aio_is_negoti‐
2898 ating(3) returns true; otherwise, the connection attempt will include
2899 the NBD handshake, and is ready for use once nbd_aio_is_ready(3) re‐
2900 turns true.
2901 val aio_connect_command : t -> string list -> unit
2905 NBD.aio_connect_command t argv
2908 connect to the NBD server
2910 Run the command as a subprocess and begin connecting to it over
2912 stdin/stdout. Parameters behave as documented in nbd_connect_com‐
2913 mand(3).
2914 You can check if the connection attempt is still underway by calling
2916 nbd_aio_is_connecting(3). If nbd_set_opt_mode(3) is enabled, the con‐
2917 nection is ready for manual option negotiation once nbd_aio_is_negoti‐
2918 ating(3) returns true; otherwise, the connection attempt will include
2919 the NBD handshake, and is ready for use once nbd_aio_is_ready(3) re‐
2920 turns true.
2921 val aio_connect_systemd_socket_activation : t -> string list -> unit
2925 NBD.aio_connect_systemd_socket_activation t argv
2928 connect using systemd socket activation
2930 Run the command as a subprocess and begin connecting to it using sys‐
2932 temd socket activation. Parameters behave as documented in nbd_con‐
2933 nect_systemd_socket_activation(3).
2934 You can check if the connection attempt is still underway by calling
2936 nbd_aio_is_connecting(3). If nbd_set_opt_mode(3) is enabled, the con‐
2937 nection is ready for manual option negotiation once nbd_aio_is_negoti‐
2938 ating(3) returns true; otherwise, the connection attempt will include
2939 the NBD handshake, and is ready for use once nbd_aio_is_ready(3) re‐
2940 turns true.
2941 val aio_opt_go : ?completion:(int Stdlib.ref -> int) -> t -> unit
2945 NBD.aio_opt_go t ?completion
2948 end negotiation and move on to using an export
2950 Request that the server finish negotiation and move on to serving the
2952 export previously specified by the most recent nbd_set_export_name(3)
2953 or nbd_connect_uri(3). This can only be used if nbd_set_opt_mode(3)
2954 enabled option mode.
2955 To determine when the request completes, wait for nbd_aio_is_connect‐
2957 ing(3) to return false. Or supply the optional "completion_callback"
2958 which will be invoked as described in "Completion callbacks" in
2959 libnbd(3), except that it is automatically retired regardless of return
2960 value. Note that directly detecting whether the server returns an error
2961 (as is done by the return value of the synchronous counterpart) is only
2962 possible with a completion callback; however it is also possible to in‐
2963 directly detect an error when nbd_aio_is_negotiating(3) returns true.
2964 val aio_opt_abort : t -> unit
2968 NBD.aio_opt_abort t
2971 end negotiation and close the connection
2973 Request that the server finish negotiation, gracefully if possible,
2975 then close the connection. This can only be used if nbd_set_opt_mode(3)
2976 enabled option mode.
2977 To determine when the request completes, wait for nbd_aio_is_connect‐
2979 ing(3) to return false.
2980 val aio_opt_starttls : ?completion:(int Stdlib.ref -> int) -> t -> unit
2984 NBD.aio_opt_starttls t ?completion
2987 request the server to initiate TLS
2989 Request that the server initiate a secure TLS connection, by sending
2991 "NBD_OPT_STARTTLS". This behaves like the synchronous counterpart
2992 nbd_opt_starttls(3), except that it does not wait for the server's re‐
2993 sponse.
2994 To determine when the request completes, wait for nbd_aio_is_connect‐
2996 ing(3) to return false. Or supply the optional "completion_callback"
2997 which will be invoked as described in "Completion callbacks" in
2998 libnbd(3), except that it is automatically retired regardless of return
2999 value. Note that detecting whether the server returns an error (as is
3000 done by the return value of the synchronous counterpart) is only possi‐
3001 ble with a completion callback.
3002 val aio_opt_extended_headers : ?completion:(int Stdlib.ref -> int) -> t
3006 -> unit
3007 NBD.aio_opt_extended_headers t ?completion
3010 request the server to enable extended headers
3012 Request that the server use extended headers, by sending "NBD_OPT_EX‐
3014 TENDED_HEADERS". This behaves like the synchronous counterpart
3015 nbd_opt_extended_headers(3), except that it does not wait for the
3016 server's response.
3017 To determine when the request completes, wait for nbd_aio_is_connect‐
3019 ing(3) to return false. Or supply the optional "completion_callback"
3020 which will be invoked as described in "Completion callbacks" in
3021 libnbd(3), except that it is automatically retired regardless of return
3022 value. Note that detecting whether the server returns an error (as is
3023 done by the return value of the synchronous counterpart) is only possi‐
3024 ble with a completion callback.
3025 val aio_opt_structured_reply : ?completion:(int Stdlib.ref -> int) -> t
3029 -> unit
3030 NBD.aio_opt_structured_reply t ?completion
3033 request the server to enable structured replies
3035 Request that the server use structured replies, by sending
3037 "NBD_OPT_STRUCTURED_REPLY". This behaves like the synchronous counter‐
3038 part nbd_opt_structured_reply(3), except that it does not wait for the
3039 server's response.
3040 To determine when the request completes, wait for nbd_aio_is_connect‐
3042 ing(3) to return false. Or supply the optional "completion_callback"
3043 which will be invoked as described in "Completion callbacks" in
3044 libnbd(3), except that it is automatically retired regardless of return
3045 value. Note that detecting whether the server returns an error (as is
3046 done by the return value of the synchronous counterpart) is only possi‐
3047 ble with a completion callback.
3048 val aio_opt_list : ?completion:(int Stdlib.ref -> int) -> t -> (string
3052 -> string -> int) -> unit
3053 NBD.aio_opt_list t ?completion list
3056 request the server to list all exports during negotiation
3058 Request that the server list all exports that it supports. This can
3060 only be used if nbd_set_opt_mode(3) enabled option mode.
3061 To determine when the request completes, wait for nbd_aio_is_connect‐
3063 ing(3) to return false. Or supply the optional "completion_callback"
3064 which will be invoked as described in "Completion callbacks" in
3065 libnbd(3), except that it is automatically retired regardless of return
3066 value. Note that detecting whether the server returns an error (as is
3067 done by the return value of the synchronous counterpart) is only possi‐
3068 ble with a completion callback.
3069 val aio_opt_info : ?completion:(int Stdlib.ref -> int) -> t -> unit
3073 NBD.aio_opt_info t ?completion
3076 request the server for information about an export
3078 Request that the server supply information about the export name previ‐
3080 ously specified by the most recent nbd_set_export_name(3) or nbd_con‐
3081 nect_uri(3). This can only be used if nbd_set_opt_mode(3) enabled op‐
3082 tion mode.
3083 To determine when the request completes, wait for nbd_aio_is_connect‐
3085 ing(3) to return false. Or supply the optional "completion_callback"
3086 which will be invoked as described in "Completion callbacks" in
3087 libnbd(3), except that it is automatically retired regardless of return
3088 value. Note that detecting whether the server returns an error (as is
3089 done by the return value of the synchronous counterpart) is only possi‐
3090 ble with a completion callback.
3091 val aio_opt_list_meta_context : ?completion:(int Stdlib.ref -> int) ->
3095 t -> (string -> int) -> int
3096 NBD.aio_opt_list_meta_context t ?completion context
3099 request list of available meta contexts, using implicit query
3101 Request that the server list available meta contexts associated with
3103 the export previously specified by the most recent nbd_set_ex‐
3104 port_name(3) or nbd_connect_uri(3), and with a list of queries from
3105 prior calls to nbd_add_meta_context(3) (see nbd_aio_opt_list_meta_con‐
3106 text_queries(3) if you want to supply an explicit query list instead).
3107 This can only be used if nbd_set_opt_mode(3) enabled option mode.
3108 To determine when the request completes, wait for nbd_aio_is_connect‐
3110 ing(3) to return false. Or supply the optional "completion_callback"
3111 which will be invoked as described in "Completion callbacks" in
3112 libnbd(3), except that it is automatically retired regardless of return
3113 value. Note that detecting whether the server returns an error (as is
3114 done by the return value of the synchronous counterpart) is only possi‐
3115 ble with a completion callback.
3116 val aio_opt_list_meta_context_queries : ?completion:(int Stdlib.ref ->
3120 int) -> t -> string list -> (string -> int) -> int
3121 NBD.aio_opt_list_meta_context_queries t ?completion queries context
3124 request list of available meta contexts, using explicit query
3126 Request that the server list available meta contexts associated with
3128 the export previously specified by the most recent nbd_set_ex‐
3129 port_name(3) or nbd_connect_uri(3), and with an explicit list of
3130 queries provided as a parameter (see nbd_aio_opt_list_meta_context(3)
3131 if you want to reuse an implicit query list instead). This can only be
3132 used if nbd_set_opt_mode(3) enabled option mode.
3133 To determine when the request completes, wait for nbd_aio_is_connect‐
3135 ing(3) to return false. Or supply the optional "completion_callback"
3136 which will be invoked as described in "Completion callbacks" in
3137 libnbd(3), except that it is automatically retired regardless of return
3138 value. Note that detecting whether the server returns an error (as is
3139 done by the return value of the synchronous counterpart) is only possi‐
3140 ble with a completion callback.
3141 val aio_opt_set_meta_context : ?completion:(int Stdlib.ref -> int) -> t
3145 -> (string -> int) -> int
3146 NBD.aio_opt_set_meta_context t ?completion context
3149 select specific meta contexts, with implicit query list
3151 Request that the server supply all recognized meta contexts registered
3153 through prior calls to nbd_add_meta_context(3), in conjunction with the
3154 export previously specified by the most recent nbd_set_export_name(3)
3155 or nbd_connect_uri(3). This can only be used if nbd_set_opt_mode(3) en‐
3156 abled option mode. Normally, this function is redundant, as
3157 nbd_opt_go(3) automatically does the same task if structured replies or
3158 extended headers have already been negotiated. But manual control over
3159 meta context requests can be useful for fine-grained testing of how a
3160 server handles unusual negotiation sequences. Often, use of this func‐
3161 tion is coupled with nbd_set_request_meta_context(3) to bypass the au‐
3162 tomatic context request normally performed by nbd_opt_go(3).
3163 To determine when the request completes, wait for nbd_aio_is_connect‐
3165 ing(3) to return false. Or supply the optional "completion_callback"
3166 which will be invoked as described in "Completion callbacks" in
3167 libnbd(3), except that it is automatically retired regardless of return
3168 value. Note that detecting whether the server returns an error (as is
3169 done by the return value of the synchronous counterpart) is only possi‐
3170 ble with a completion callback.
3171 val aio_opt_set_meta_context_queries : ?completion:(int Stdlib.ref ->
3175 int) -> t -> string list -> (string -> int) -> int
3176 NBD.aio_opt_set_meta_context_queries t ?completion queries context
3179 select specific meta contexts, with explicit query list
3181 Request that the server supply all recognized meta contexts passed in
3183 through "queries", in conjunction with the export previously specified
3184 by the most recent nbd_set_export_name(3) or nbd_connect_uri(3). This
3185 can only be used if nbd_set_opt_mode(3) enabled option mode. Normally,
3186 this function is redundant, as nbd_opt_go(3) automatically does the
3187 same task if structured replies or extended headers have already been
3188 negotiated. But manual control over meta context requests can be useful
3189 for fine-grained testing of how a server handles unusual negotiation
3190 sequences. Often, use of this function is coupled with nbd_set_re‐
3191 quest_meta_context(3) to bypass the automatic context request normally
3192 performed by nbd_opt_go(3).
3193 To determine when the request completes, wait for nbd_aio_is_connect‐
3195 ing(3) to return false. Or supply the optional "completion_callback"
3196 which will be invoked as described in "Completion callbacks" in
3197 libnbd(3), except that it is automatically retired regardless of return
3198 value. Note that detecting whether the server returns an error (as is
3199 done by the return value of the synchronous counterpart) is only possi‐
3200 ble with a completion callback.
3201 val aio_pread : ?completion:(int Stdlib.ref -> int) ->
3205 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> cookie
3206 NBD.aio_pread t ?completion ?flags buf offset
3209 read from the NBD server
3211 Issue a read command to the NBD server.
3213 To check if the command completed, call nbd_aio_command_completed(3).
3215 Or supply the optional "completion_callback" which will be invoked as
3216 described in "Completion callbacks" in libnbd(3).
3217 Note that you must ensure "buf" is valid until the command has com‐
3219 pleted. Furthermore, if the "error" parameter to "completion_callback"
3220 is set or if nbd_aio_command_completed(3) reports failure, and if
3221 nbd_get_pread_initialize(3) returns true, then libnbd sanitized "buf",
3222 but it is unspecified whether the contents of "buf" will read as zero
3223 or as partial results from the server. If nbd_get_pread_initialize(3)
3224 returns false, then libnbd did not sanitize "buf", and the contents are
3225 undefined on failure.
3226 Other parameters behave as documented in nbd_pread(3).
3228 By default, libnbd will reject attempts to use this function with pa‐
3230 rameters that are likely to result in server failure, such as request‐
3231 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
3232 used to alter which scenarios should await a server reply rather than
3233 failing fast.
3234 val aio_pread_structured : ?completion:(int Stdlib.ref -> int) ->
3238 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> (bytes -> int64 ->
3239 int -> int Stdlib.ref -> int) -> cookie
3240 NBD.aio_pread_structured t ?completion ?flags buf offset chunk
3243 read from the NBD server
3245 Issue a read command to the NBD server.
3247 To check if the command completed, call nbd_aio_command_completed(3).
3249 Or supply the optional "completion_callback" which will be invoked as
3250 described in "Completion callbacks" in libnbd(3).
3251 Note that you must ensure "buf" is valid until the command has com‐
3253 pleted. Furthermore, if the "error" parameter to "completion_callback"
3254 is set or if nbd_aio_command_completed(3) reports failure, and if
3255 nbd_get_pread_initialize(3) returns true, then libnbd sanitized "buf",
3256 but it is unspecified whether the contents of "buf" will read as zero
3257 or as partial results from the server. If nbd_get_pread_initialize(3)
3258 returns false, then libnbd did not sanitize "buf", and the contents are
3259 undefined on failure.
3260 Other parameters behave as documented in nbd_pread_structured(3).
3262 By default, libnbd will reject attempts to use this function with pa‐
3264 rameters that are likely to result in server failure, such as request‐
3265 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
3266 used to alter which scenarios should await a server reply rather than
3267 failing fast.
3268 val aio_pwrite : ?completion:(int Stdlib.ref -> int) ->
3272 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> cookie
3273 NBD.aio_pwrite t ?completion ?flags buf offset
3276 write to the NBD server
3278 Issue a write command to the NBD server.
3280 To check if the command completed, call nbd_aio_command_completed(3).
3282 Or supply the optional "completion_callback" which will be invoked as
3283 described in "Completion callbacks" in libnbd(3).
3284 Note that you must ensure "buf" is valid until the command has com‐
3286 pleted. Other parameters behave as documented in nbd_pwrite(3).
3287 By default, libnbd will reject attempts to use this function with pa‐
3289 rameters that are likely to result in server failure, such as request‐
3290 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
3291 used to alter which scenarios should await a server reply rather than
3292 failing fast.
3293 val aio_disconnect : ?flags:CMD_FLAG.t list -> t -> unit
3297 NBD.aio_disconnect t ?flags
3300 disconnect from the NBD server
3302 Issue the disconnect command to the NBD server. This is not a normal
3304 command because NBD servers are not obliged to send a reply. Instead
3305 you should wait for nbd_aio_is_closed(3) to become true on the connec‐
3306 tion. Once this command is issued, you cannot issue any further com‐
3307 mands.
3308 Although libnbd does not prevent you from issuing this command while
3310 still waiting on the replies to previous commands, the NBD protocol
3311 recommends that you wait until there are no other commands in flight
3312 (see nbd_aio_in_flight(3)), to give the server a better chance at a
3313 clean shutdown.
3314 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
3316 tocol extensions). There is no direct synchronous counterpart; however,
3317 nbd_shutdown(3) will call this function if appropriate.
3318 val aio_flush : ?completion:(int Stdlib.ref -> int) ->
3322 ?flags:CMD_FLAG.t list -> t -> cookie
3323 NBD.aio_flush t ?completion ?flags
3326 send flush command to the NBD server
3328 Issue the flush command to the NBD server.
3330 To check if the command completed, call nbd_aio_command_completed(3).
3332 Or supply the optional "completion_callback" which will be invoked as
3333 described in "Completion callbacks" in libnbd(3).
3334 Other parameters behave as documented in nbd_flush(3).
3336 By default, libnbd will reject attempts to use this function with pa‐
3338 rameters that are likely to result in server failure, such as request‐
3339 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
3340 used to alter which scenarios should await a server reply rather than
3341 failing fast.
3342 val aio_trim : ?completion:(int Stdlib.ref -> int) -> ?flags:CMD_FLAG.t
3346 list -> t -> int64 -> int64 -> cookie
3347 NBD.aio_trim t ?completion ?flags count offset
3350 send trim command to the NBD server
3352 Issue a trim command to the NBD server.
3354 To check if the command completed, call nbd_aio_command_completed(3).
3356 Or supply the optional "completion_callback" which will be invoked as
3357 described in "Completion callbacks" in libnbd(3).
3358 Other parameters behave as documented in nbd_trim(3).
3360 By default, libnbd will reject attempts to use this function with pa‐
3362 rameters that are likely to result in server failure, such as request‐
3363 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
3364 used to alter which scenarios should await a server reply rather than
3365 failing fast.
3366 val aio_cache : ?completion:(int Stdlib.ref -> int) ->
3370 ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> cookie
3371 NBD.aio_cache t ?completion ?flags count offset
3374 send cache (prefetch) command to the NBD server
3376 Issue the cache (prefetch) command to the NBD server.
3378 To check if the command completed, call nbd_aio_command_completed(3).
3380 Or supply the optional "completion_callback" which will be invoked as
3381 described in "Completion callbacks" in libnbd(3).
3382 Other parameters behave as documented in nbd_cache(3).
3384 By default, libnbd will reject attempts to use this function with pa‐
3386 rameters that are likely to result in server failure, such as request‐
3387 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
3388 used to alter which scenarios should await a server reply rather than
3389 failing fast.
3390 val aio_zero : ?completion:(int Stdlib.ref -> int) -> ?flags:CMD_FLAG.t
3394 list -> t -> int64 -> int64 -> cookie
3395 NBD.aio_zero t ?completion ?flags count offset
3398 send write zeroes command to the NBD server
3400 Issue a write zeroes command to the NBD server.
3402 To check if the command completed, call nbd_aio_command_completed(3).
3404 Or supply the optional "completion_callback" which will be invoked as
3405 described in "Completion callbacks" in libnbd(3).
3406 Other parameters behave as documented in nbd_zero(3).
3408 By default, libnbd will reject attempts to use this function with pa‐
3410 rameters that are likely to result in server failure, such as request‐
3411 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
3412 used to alter which scenarios should await a server reply rather than
3413 failing fast.
3414 val aio_block_status : ?completion:(int Stdlib.ref -> int) ->
3418 ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> (string -> int64 ->
3419 int64 array -> int Stdlib.ref -> int) -> cookie
3420 NBD.aio_block_status t ?completion ?flags count offset extent
3423 send block status command, with 32-bit callback
3425 Send the block status command to the NBD server.
3427 To check if the command completed, call nbd_aio_command_completed(3).
3429 Or supply the optional "completion_callback" which will be invoked as
3430 described in "Completion callbacks" in libnbd(3).
3431 Other parameters behave as documented in nbd_block_status(3).
3433 This function is inherently limited to 32-bit values. If the server
3435 replies with a larger extent, the length of that extent will be trun‐
3436 cated to just below 32 bits and any further extents from the server
3437 will be ignored. If the server replies with a status value larger than
3438 32 bits (only possible when extended headers are in use), the callback
3439 function will be passed an "EOVERFLOW" error. To get the full extent
3440 information from a server that supports 64-bit extents, you must use
3441 nbd_aio_block_status_64(3).
3442 By default, libnbd will reject attempts to use this function with pa‐
3444 rameters that are likely to result in server failure, such as request‐
3445 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
3446 used to alter which scenarios should await a server reply rather than
3447 failing fast.
3448 val aio_block_status_64 : ?completion:(int Stdlib.ref -> int) ->
3452 ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> (string -> int64 ->
3453 extent array -> int Stdlib.ref -> int) -> cookie
3454 NBD.aio_block_status_64 t ?completion ?flags count offset extent64
3457 send block status command, with 64-bit callback
3459 Send the block status command to the NBD server.
3461 To check if the command completed, call nbd_aio_command_completed(3).
3463 Or supply the optional "completion_callback" which will be invoked as
3464 described in "Completion callbacks" in libnbd(3).
3465 Other parameters behave as documented in nbd_block_status_64(3).
3467 By default, libnbd will reject attempts to use this function with pa‐
3469 rameters that are likely to result in server failure, such as request‐
3470 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
3471 used to alter which scenarios should await a server reply rather than
3472 failing fast.
3473 val aio_block_status_filter : ?completion:(int Stdlib.ref -> int) ->
3477 ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> string list -> (string
3478 -> int64 -> extent array -> int Stdlib.ref -> int) -> cookie
3479 NBD.aio_block_status_filter t ?completion ?flags count offset contexts
3482 extent64
3483 send filtered block status command to the NBD server
3485 Send a filtered block status command to the NBD server.
3487 To check if the command completed, call nbd_aio_command_completed(3).
3489 Or supply the optional "completion_callback" which will be invoked as
3490 described in "Completion callbacks" in libnbd(3).
3491 Other parameters behave as documented in nbd_block_status_filter(3).
3493 By default, libnbd will reject attempts to use this function with pa‐
3495 rameters that are likely to result in server failure, such as request‐
3496 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
3497 used to alter which scenarios should await a server reply rather than
3498 failing fast.
3499 val aio_get_fd : t -> Unix.file_descr
3503 NBD.aio_get_fd t
3506 return file descriptor associated with this connection
3508 Return the underlying file descriptor associated with this connection.
3510 You can use this to check if the file descriptor is ready for reading
3511 or writing and call nbd_aio_notify_read(3) or nbd_aio_notify_write(3).
3512 See also nbd_aio_get_direction(3). Do not do anything else with the
3513 file descriptor.
3514 val aio_get_direction : t -> int
3518 NBD.aio_get_direction t
3521 return the read or write direction
3523 Return the current direction of this connection, which means whether we
3525 are next expecting to read data from the server, write data to the
3526 server, or both. It returns
3527 0 We are not expected to interact with the server file descriptor
3529 from the current state. It is not worth attempting to use poll(2); if
3530 the connection is not dead, then state machine progress must instead
3531 come from some other means such as nbd_aio_connect(3).
3532 "LIBNBD_AIO_DIRECTION_READ" = 1 We are expected next to read from the
3534 server. If using poll(2) you would set "events = POLLIN". If "revents"
3535 returns "POLLIN" or "POLLHUP" you would then call nbd_aio_no‐
3536 tify_read(3).
3537 Note that once libnbd reaches nbd_aio_is_ready(3), this direction is
3539 returned even when there are no commands in flight (see
3540 nbd_aio_in_flight(3)). In a single-threaded use of libnbd, it is not
3541 worth polling until after issuing a command, as otherwise the server
3542 will never wake up the poll. In a multi-threaded scenario, you can have
3543 one thread begin a polling loop prior to any commands, but any other
3544 thread that issues a command will need a way to kick the polling thread
3545 out of poll in case issuing the command changes the needed polling di‐
3546 rection. Possible ways to do this include polling for activity on a
3547 pipe-to-self, or using pthread_kill(3) to send a signal that is masked
3548 except during ppoll(2).
3549 "LIBNBD_AIO_DIRECTION_WRITE" = 2 We are expected next to write to the
3551 server. If using poll(2) you would set "events = POLLOUT". If "revents"
3552 returns "POLLOUT" you would then call nbd_aio_notify_write(3).
3553 "LIBNBD_AIO_DIRECTION_BOTH" = 3 We are expected next to either read or
3555 write to the server. If using poll(2) you would set "events =
3556 POLLIN|POLLOUT". If only one of "POLLIN" or "POLLOUT" is returned, then
3557 see above. However, if both are returned, it is better to call only
3558 nbd_aio_notify_read(3), as processing the server's reply may change the
3559 state of the connection and invalidate the need to write more commands.
3560 val aio_notify_read : t -> unit
3564 NBD.aio_notify_read t
3567 notify that the connection is readable
3569 Send notification to the state machine that the connection is readable.
3571 Typically this is called after your main loop has detected that the
3572 file descriptor associated with this connection is readable.
3573 val aio_notify_write : t -> unit
3577 NBD.aio_notify_write t
3580 notify that the connection is writable
3582 Send notification to the state machine that the connection is writable.
3584 Typically this is called after your main loop has detected that the
3585 file descriptor associated with this connection is writable.
3586 val aio_is_created : t -> bool
3590 NBD.aio_is_created t
3593 check if the connection has just been created
3595 Return true if this connection has just been created. This is the
3597 state before the handle has started connecting to a server. In this
3598 state the handle can start to be connected by calling functions such as
3599 nbd_aio_connect(3).
3600 val aio_is_connecting : t -> bool
3604 NBD.aio_is_connecting t
3607 check if the connection is connecting or handshaking
3609 Return true if this connection is connecting to the server or in the
3611 process of handshaking and negotiating options which happens before the
3612 handle becomes ready to issue commands (see nbd_aio_is_ready(3)).
3613 val aio_is_negotiating : t -> bool
3617 NBD.aio_is_negotiating t
3620 check if connection is ready to send handshake option
3622 Return true if this connection is ready to start another option negoti‐
3624 ation command while handshaking with the server. An option command will
3625 move back to the connecting state (see nbd_aio_is_connecting(3)). Note
3626 that this state cannot be reached unless requested by
3627 nbd_set_opt_mode(3), and even then it only works with newstyle servers;
3628 an oldstyle server will skip straight to nbd_aio_is_ready(3).
3629 val aio_is_ready : t -> bool
3633 NBD.aio_is_ready t
3636 check if the connection is in the ready state
3638 Return true if this connection is connected to the NBD server, the
3640 handshake has completed, and the connection is idle or waiting for a
3641 reply. In this state the handle is ready to issue commands.
3642 val aio_is_processing : t -> bool
3646 NBD.aio_is_processing t
3649 check if the connection is processing a command
3651 Return true if this connection is connected to the NBD server, the
3653 handshake has completed, and the connection is processing commands (ei‐
3654 ther writing out a request or reading a reply).
3655 Note the ready state (nbd_aio_is_ready(3)) is not included. In the
3657 ready state commands may be *in flight* (the *server* is processing
3658 them), but libnbd is not processing them.
3659 val aio_is_dead : t -> bool
3663 NBD.aio_is_dead t
3666 check if the connection is dead
3668 Return true if the connection has encountered a fatal error and is
3670 dead. In this state the handle may only be closed. There is no way to
3671 recover a handle from the dead state.
3672 val aio_is_closed : t -> bool
3676 NBD.aio_is_closed t
3679 check if the connection is closed
3681 Return true if the connection has closed. There is no way to reconnect
3683 a closed connection. Instead you must close the whole handle.
3684 val aio_command_completed : t -> int64 -> bool
3688 NBD.aio_command_completed t cookie
3691 check if the command completed
3693 Return true if the command completed. If this function returns true
3695 then the command was successful and it has been retired. Return false
3696 if the command is still in flight. This can also fail with an error in
3697 case the command failed (in this case the command is also retired). A
3698 command is retired either via this command, or by using a completion
3699 callback which returns 1.
3700 The "cookie" parameter is the positive unique 64 bit cookie for the
3702 command, as returned by a call such as nbd_aio_pread(3).
3703 val aio_peek_command_completed : t -> int64
3707 NBD.aio_peek_command_completed t
3710 check if any command has completed
3712 Return the unique positive 64 bit cookie of the first non-retired but
3714 completed command, 0 if there are in-flight commands but none of them
3715 are awaiting retirement, or -1 on error including when there are no
3716 in-flight commands. Any cookie returned by this function must still be
3717 passed to nbd_aio_command_completed(3) to actually retire the command
3718 and learn whether the command was successful.
3719 val aio_in_flight : t -> int
3723 NBD.aio_in_flight t
3726 check how many aio commands are still in flight
3728 Return the number of in-flight aio commands that are still awaiting a
3730 response from the server before they can be retired. If this returns a
3731 non-zero value when requesting a disconnect from the server (see
3732 nbd_aio_disconnect(3) and nbd_shutdown(3)), libnbd does not try to wait
3733 for those commands to complete gracefully; if the server strands com‐
3734 mands while shutting down, nbd_aio_command_completed(3) will report
3735 those commands as failed with a status of "ENOTCONN".
3736 val connection_state : t -> string
3740 NBD.connection_state t
3743 return string describing the state of the connection
3745 Returns a descriptive string for the state of the connection. This can
3747 be used for debugging or troubleshooting, but you should not rely on
3748 the state of connections since it may change in future versions.
3749 val get_package_name : t -> string
3753 NBD.get_package_name t
3756 return the name of the library
3758 Returns the name of the library, always "libnbd" unless the library was
3760 modified with another name at compile time.
3761 val get_version : t -> string
3765 NBD.get_version t
3768 return the version of the library
3770 Return the version of libnbd. This is returned as a string in the form
3772 "major.minor.release" where each of major, minor and release is a small
3773 positive integer. For example:
3774 minor ↓ "1.0.3" ↑ ↑ major release
3776 major = 0 The major number was 0 for the early experimental versions of
3778 libnbd where we still had an unstable API.
3779 major = 1 The major number is 1 for the versions of libnbd with a
3781 long-term stable API and ABI. It is not anticipated that major will be
3782 any number other than 1.
3783 minor = 0, 2, ... (even) The minor number is even for stable releases.
3785 minor = 1, 3, ... (odd) The minor number is odd for development ver‐
3787 sions. Note that new APIs added in a development version remain exper‐
3788 imental and subject to change in that branch until they appear in a
3789 stable release.
3790 release The release number is incremented for each release along a par‐
3792 ticular branch.
3793 val kill_subprocess : t -> int -> unit
3797 NBD.kill_subprocess t signum
3800 kill server running as a subprocess
3802 This call may be used to kill the server running as a subprocess that
3804 was previously created using nbd_connect_command(3). You do not need to
3805 use this call. It is only needed if the server does not exit when the
3806 socket is closed.
3807 The "signum" parameter is the optional signal number to send (see sig‐
3809 nal(7)). If "signum" is 0 then "SIGTERM" is sent.
3810 val supports_tls : t -> bool
3814 NBD.supports_tls t
3817 true if libnbd was compiled with support for TLS
3819 Returns true if libnbd was compiled with gnutls which is required to
3821 support TLS encryption, or false if not.
3822 val supports_vsock : t -> bool
3826 NBD.supports_vsock t
3829 true if libnbd was compiled with support for AF_VSOCK
3831 Returns true if libnbd was compiled with support for the "AF_VSOCK"
3833 family of sockets, or false if not.
3834 Note that on the Linux operating system, this returns true if there is
3836 compile-time support, but you may still need runtime support for some
3837 aspects of AF_VSOCK usage; for example, use of "VMADDR_CID_LOCAL" as
3838 the server name requires that the *vsock_loopback* kernel module is
3839 loaded.
3840 val supports_uri : t -> bool
3844 NBD.supports_uri t
3847 true if libnbd was compiled with support for NBD URIs
3849 Returns true if libnbd was compiled with libxml2 which is required to
3851 support NBD URIs, or false if not.
3852 val get_uri : t -> string
3856 NBD.get_uri t
3859 construct an NBD URI for a connection
3861 This makes a best effort attempt to construct an NBD URI which could be
3863 used to connect back to the same server (using nbd_connect_uri(3)).
3864 In some cases there is not enough information in the handle to success‐
3866 fully create a URI (eg. if you connected with nbd_connect_socket(3)).
3867 In such cases the call returns "NULL" and further diagnostic informa‐
3868 tion is available via nbd_get_errno(3) and nbd_get_error(3) as usual.
3869 Even if a URI is returned it is not guaranteed to work, and it may not
3871 be optimal.
3872OCamldoc 2023-10-31 NBD(3)