1NBD(3) NBD(3)
2
6 NBD - OCaml bindings for libnbd.
7
9 Module NBD
10
12 Module NBD
13 : sig end
14 OCaml bindings for libnbd.
17 For full documentation see libnbd-ocaml(3) and libnbd(3).
19 For examples written in OCaml see the libnbd source code ocaml/examples
21 subdirectory.
22 exception Error of string * int
29 Exception thrown when an API call fails.
32 The string is the error message, and the int is the raw errno (if
34 available).
35 exception Closed of string
39 Exception thrown if you call a closed handle.
42 type cookie = int64
45 module TLS : sig end
50 module SIZE : sig end
55 module CMD_FLAG : sig end
60 module HANDSHAKE_FLAG : sig end
65 module STRICT : sig end
70 module ALLOW_TRANSPORT : sig end
75 module SHUTDOWN : sig end
80 val aio_direction_read : int32
86 val aio_direction_write : int32
91 val aio_direction_both : int32
96 val read_data : int32
101 val read_hole : int32
106 val read_error : int32
111 val namespace_base : string
116 val context_base_allocation : string
121 val state_hole : int32
126 val state_zero : int32
131 module Buffer : sig end
135 Persistent buffer used in AIO calls.
138 type t
141 The handle.
144 val create : unit -> t
148 Create a new handle.
150 val close : t -> unit
154 Close a handle.
156 Handles can also be closed by the garbage collector when they become
158 unreachable. This call is used only if you want to force the handle to
159 close now and reclaim resources immediately.
160 val with_handle : (t -> 'a) -> 'a
164 Wrapper around NBD.create . It calls the function parameter with a
166 newly created handle, and ensures that NBD.close is always called even
167 if the function throws an exception.
168 Use this when it is essential that the handle is closed in order to
170 free up external resources in a timely manner; for example if running
171 the server as a subprocess and you want to ensure that the subprocess
172 is always killed; or if you need to disconnect from the server before
173 continuing with another operation.
174 val set_debug : t -> bool -> unit
178 set or clear the debug flag
180 Set or clear the debug flag. When debugging is enabled, debugging mes‐
182 sages from the library are printed to stderr, unless a debugging call‐
183 back has been defined too (see nbd_set_debug_callback(3)) in which case
184 they are sent to that function. This flag defaults to false on newly
185 created handles, except if "LIBNBD_DEBUG=1" is set in the environment
186 in which case it defaults to true.
187 val get_debug : t -> bool
191 return the state of the debug flag
193 Return the state of the debug flag on this handle.
195 val set_debug_callback : t -> (string -> string -> int) -> unit
199 set the debug callback
201 Set the debug callback. This function is called when the library emits
203 debug messages, when debugging is enabled on a handle. The callback pa‐
204 rameters are "user_data" passed to this function, the name of the
205 libnbd function emitting the debug message ("context"), and the message
206 itself ("msg"). If no debug callback is set on a handle then messages
207 are printed on "stderr".
208 The callback should not call "nbd_*" APIs on the same handle since it
210 can be called while holding the handle lock and will cause a deadlock.
211 val clear_debug_callback : t -> unit
215 clear the debug callback
217 Remove the debug callback if one was previously associated with the
219 handle (with nbd_set_debug_callback(3)). If no callback was associated
220 this does nothing.
221 val set_handle_name : t -> string -> unit
225 set the handle name
227 Handles have a name which is unique within the current process. The
229 handle name is used in debug output.
230 Handle names are normally generated automatically and have the form
232 "nbd1", "nbd2", etc., but you can optionally use this call to give the
233 handles a name which is meaningful for your application to make debug‐
234 ging output easier to understand.
235 val get_handle_name : t -> string
239 get the handle name
241 Get the name of the handle. If it was previously set by calling
243 nbd_set_handle_name(3) then this returns the name that was set. Other‐
244 wise it will return a generic name like "nbd1", "nbd2", etc.
245 val set_private_data : t -> int -> int
249 set the per-handle private data
251 Handles contain a private data field for applications to use for any
253 purpose.
254 When calling libnbd from C, the type of this field is "uintptr_t" so it
256 can be used to store an unsigned integer or a pointer.
257 In non-C bindings it can be used to store an unsigned integer.
259 This function sets the value of this field and returns the old value
261 (or 0 if it was not previously set).
262 val get_private_data : t -> int
266 get the per-handle private data
268 Return the value of the private data field set previously by a call to
270 nbd_set_private_data(3) (or 0 if it was not previously set).
271 val set_export_name : t -> string -> unit
275 set the export name
277 For servers which require an export name or can serve different content
279 on different exports, set the "export_name" to connect to. The default
280 is the empty string "".
281 This is only relevant when connecting to servers using the newstyle
283 protocol as the oldstyle protocol did not support export names. The NBD
284 protocol limits export names to 4096 bytes, but servers may not support
285 the full length. The encoding of export names is always UTF-8.
286 When option mode is not in use, the export name must be set before be‐
288 ginning a connection. However, when nbd_set_opt_mode(3) has enabled op‐
289 tion mode, it is possible to change the export name prior to
290 nbd_opt_go(3). In particular, the use of nbd_opt_list(3) during negoti‐
291 ation can be used to determine a name the server is likely to accept,
292 and nbd_opt_info(3) can be used to learn details about an export before
293 connecting.
294 This call may be skipped if using nbd_connect_uri(3) to connect to a
296 URI that includes an export name.
297 val get_export_name : t -> string
301 get the export name
303 Get the export name associated with the handle. This is the name that
305 libnbd requests; see nbd_get_canonical_export_name(3) for determining
306 if the server has a different canonical name for the given export (most
307 common when requesting the default export name of an empty string "")
308 val set_request_block_size : t -> bool -> unit
312 control whether NBD_OPT_GO requests block size
314 By default, when connecting to an export, libnbd requests that the
316 server report any block size restrictions. The NBD protocol states that
317 a server may supply block sizes regardless of whether the client re‐
318 quests them, and libnbd will report those block sizes (see
319 nbd_get_block_size(3)); conversely, if a client does not request block
320 sizes, the server may reject the connection instead of dealing with a
321 client sending unaligned requests. This function makes it possible to
322 test server behavior by emulating older clients.
323 Note that even when block size is requested, the server is not obli‐
325 gated to provide any. Furthermore, if block sizes are provided (whether
326 or not the client requested them), libnbd enforces alignment to those
327 sizes unless nbd_set_strict_mode(3) is used to bypass client-side
328 safety checks.
329 val get_request_block_size : t -> bool
333 see if NBD_OPT_GO requests block size
335 Return the state of the block size request flag on this handle.
337 val set_full_info : t -> bool -> unit
341 control whether NBD_OPT_GO requests extra details
343 By default, when connecting to an export, libnbd only requests the de‐
345 tails it needs to service data operations. The NBD protocol says that a
346 server can supply optional information, such as a canonical name of the
347 export (see nbd_get_canonical_export_name(3)) or a description of the
348 export (see nbd_get_export_description(3)), but that a hint from the
349 client makes it more likely for this extra information to be provided.
350 This function controls whether libnbd will provide that hint.
351 Note that even when full info is requested, the server is not obligated
353 to reply with all information that libnbd requested. Similarly, libnbd
354 will ignore any optional server information that libnbd has not yet
355 been taught to recognize. Furthermore, the hint to request block sizes
356 is independently controlled via nbd_set_request_block_size(3).
357 val get_full_info : t -> bool
361 see if NBD_OPT_GO requests extra details
363 Return the state of the full info request flag on this handle.
365 val get_canonical_export_name : t -> string
369 return the canonical export name, if the server has one
371 The NBD protocol permits a server to report an optional canonical ex‐
373 port name, which may differ from the client's request (as set by
374 nbd_set_export_name(3) or nbd_connect_uri(3)). This function accesses
375 any name returned by the server; it may be the same as the client re‐
376 quest, but is more likely to differ when the client requested a connec‐
377 tion to the default export name (an empty string "").
378 Some servers are unlikely to report a canonical name unless the client
380 specifically hinted about wanting it, via nbd_set_full_info(3).
381 val get_export_description : t -> string
385 return the export description, if the server has one
387 The NBD protocol permits a server to report an optional export descrip‐
389 tion. This function reports any description returned by the server.
390 Some servers are unlikely to report a description unless the client
392 specifically hinted about wanting it, via nbd_set_full_info(3). For
393 qemu-nbd(8), a description is set with *-D*.
394 val set_tls : t -> TLS.t -> unit
398 enable or require TLS (authentication and encryption)
400 Enable or require TLS (authenticated and encrypted connections) to the
402 NBD server. The possible settings are:
403 "LIBNBD_TLS_DISABLE" Disable TLS. (The default setting, unless using
405 nbd_connect_uri(3) with a URI that requires TLS)
406 "LIBNBD_TLS_ALLOW" Enable TLS if possible.
408 This option is insecure (or best effort) in that in some cases it will
410 fall back to an unencrypted and/or unauthenticated connection if TLS
411 could not be established. Use "LIBNBD_TLS_REQUIRE" below if the connec‐
412 tion must be encrypted.
413 Some servers will drop the connection if TLS fails so fallback may not
415 be possible.
416 "LIBNBD_TLS_REQUIRE" Require an encrypted and authenticated TLS connec‐
418 tion. Always fail to connect if the connection is not encrypted and au‐
419 thenticated.
420 As well as calling this you may also need to supply the path to the
422 certificates directory (nbd_set_tls_certificates(3)), the username
423 (nbd_set_tls_username(3)) and/or the Pre-Shared Keys (PSK) file
424 (nbd_set_tls_psk_file(3)). For now, when using nbd_connect_uri(3), any
425 URI query parameters related to TLS are not handled automatically. Set‐
426 ting the level higher than zero will fail if libnbd was not compiled
427 against gnutls; you can test whether this is the case with nbd_sup‐
428 ports_tls(3).
429 val get_tls : t -> TLS.t
433 get the TLS request setting
435 Get the TLS request setting.
437 Note: If you want to find out if TLS was actually negotiated on a par‐
439 ticular connection use nbd_get_tls_negotiated(3) instead.
440 val get_tls_negotiated : t -> bool
444 find out if TLS was negotiated on a connection
446 After connecting you may call this to find out if the connection is us‐
448 ing TLS.
449 This is only really useful if you set the TLS request mode to
451 "LIBNBD_TLS_ALLOW" (see nbd_set_tls(3)), because in this mode we try to
452 use TLS but fall back to unencrypted if it was not available. This
453 function will tell you if TLS was negotiated or not.
454 In "LIBNBD_TLS_REQUIRE" mode (the most secure) the connection would
456 have failed if TLS could not be negotiated, and in "LIBNBD_TLS_DISABLE"
457 mode TLS is not tried.
458 val set_tls_certificates : t -> string -> unit
462 set the path to the TLS certificates directory
464 Set the path to the TLS certificates directory. If not set and TLS is
466 used then a compiled in default is used. For root this is
467 "/etc/pki/libnbd/". For non-root this is "$HOME/.pki/libnbd" and
468 "$HOME/.config/pki/libnbd". If none of these directories can be found
469 then the system trusted CAs are used.
470 This function may be called regardless of whether TLS is supported, but
472 will have no effect unless nbd_set_tls(3) is also used to request or
473 require TLS.
474 val set_tls_verify_peer : t -> bool -> unit
478 set whether we verify the identity of the server
480 Set this flag to control whether libnbd will verify the identity of the
482 server from the server's certificate and the certificate authority.
483 This defaults to true when connecting to TCP servers using TLS certifi‐
484 cate authentication, and false otherwise.
485 This function may be called regardless of whether TLS is supported, but
487 will have no effect unless nbd_set_tls(3) is also used to request or
488 require TLS.
489 val get_tls_verify_peer : t -> bool
493 get whether we verify the identity of the server
495 Get the verify peer flag.
497 val set_tls_username : t -> string -> unit
501 set the TLS username
503 Set the TLS client username. This is used if authenticating with PSK
505 over TLS is enabled. If not set then the local username is used.
506 This function may be called regardless of whether TLS is supported, but
508 will have no effect unless nbd_set_tls(3) is also used to request or
509 require TLS.
510 val get_tls_username : t -> string
514 get the current TLS username
516 Get the current TLS username.
518 val set_tls_psk_file : t -> string -> unit
522 set the TLS Pre-Shared Keys (PSK) filename
524 Set the TLS Pre-Shared Keys (PSK) filename. This is used if trying to
526 authenticate to the server using with a pre-shared key. There is no de‐
527 fault so if this is not set then PSK authentication cannot be used to
528 connect to the server.
529 This function may be called regardless of whether TLS is supported, but
531 will have no effect unless nbd_set_tls(3) is also used to request or
532 require TLS.
533 val set_request_structured_replies : t -> bool -> unit
537 control use of structured replies
539 By default, libnbd tries to negotiate structured replies with the
541 server, as this protocol extension must be in use before
542 nbd_can_meta_context(3) or nbd_can_df(3) can return true. However, for
543 integration testing, it can be useful to clear this flag rather than
544 find a way to alter the server to fail the negotiation request.
545 val get_request_structured_replies : t -> bool
549 see if structured replies are attempted
551 Return the state of the request structured replies flag on this handle.
553 Note: If you want to find out if structured replies were actually nego‐
555 tiated on a particular connection use nbd_get_structured_replies_nego‐
556 tiated(3) instead.
557 val get_structured_replies_negotiated : t -> bool
561 see if structured replies are in use
563 After connecting you may call this to find out if the connection is us‐
565 ing structured replies.
566 val set_handshake_flags : t -> HANDSHAKE_FLAG.t list -> unit
570 control use of handshake flags
572 By default, libnbd tries to negotiate all possible handshake flags that
574 are also supported by the server, since omitting a handshake flag can
575 prevent the use of other functionality such as TLS encryption or struc‐
576 tured replies. However, for integration testing, it can be useful to
577 reduce the set of flags supported by the client to test that a particu‐
578 lar server can handle various clients that were compliant to older ver‐
579 sions of the NBD specification.
580 The "flags" argument is a bitmask, including zero or more of the fol‐
582 lowing handshake flags:
583 "LIBNBD_HANDSHAKE_FLAG_FIXED_NEWSTYLE" = 1 The server gracefully han‐
585 dles unknown option requests from the client, rather than disconnect‐
586 ing. Without this flag, a client cannot safely request to use exten‐
587 sions such as TLS encryption or structured replies, as the request may
588 cause an older server to drop the connection.
589 "LIBNBD_HANDSHAKE_FLAG_NO_ZEROES" = 2 If the client is forced to use
591 "NBD_OPT_EXPORT_NAME" instead of the preferred "NBD_OPT_GO", this flag
592 allows the server to send fewer all-zero padding bytes over the connec‐
593 tion.
594 For convenience, the constant "LIBNBD_HANDSHAKE_FLAG_MASK" is available
596 to describe all flags supported by this build of libnbd. Future NBD ex‐
597 tensions may add further flags, which in turn may be enabled by default
598 in newer libnbd. As such, when attempting to disable only one specific
599 bit, it is wiser to first call nbd_get_handshake_flags(3) and modify
600 that value, rather than blindly setting a constant value.
601 val get_handshake_flags : t -> HANDSHAKE_FLAG.t list
605 see which handshake flags are supported
607 Return the state of the handshake flags on this handle. When the han‐
609 dle has not yet completed a connection (see nbd_aio_is_created(3)),
610 this returns the flags that the client is willing to use, provided the
611 server also advertises those flags. After the connection is ready (see
612 nbd_aio_is_ready(3)), this returns the flags that were actually agreed
613 on between the server and client. If the NBD protocol defines new
614 handshake flags, then the return value from a newer library version may
615 include bits that were undefined at the time of compilation.
616 val set_pread_initialize : t -> bool -> unit
620 control whether libnbd pre-initializes read buffers
622 By default, libnbd will pre-initialize the contents of a buffer passed
624 to calls such as nbd_pread(3) to all zeroes prior to checking for any
625 other errors, so that even if a client application passed in an unini‐
626 tialized buffer but fails to check for errors, it will not result in a
627 potential security risk caused by an accidental leak of prior heap con‐
628 tents (see CVE-2022-0485 in libnbd-security(3) for an example of a se‐
629 curity hole in an application built against an earlier version of
630 libnbd that lacked consistent pre-initialization). However, for a
631 client application that has audited that an uninitialized buffer is
632 never dereferenced, or which performs its own pre-initialization,
633 libnbd's sanitization efforts merely pessimize performance (although
634 the time spent in pre-initialization may pale in comparison to time
635 spent waiting on network packets).
636 Calling this function with "request" set to false tells libnbd to skip
638 the buffer initialization step in read commands.
639 val get_pread_initialize : t -> bool
643 see whether libnbd pre-initializes read buffers
645 Return whether libnbd performs a pre-initialization of a buffer passed
647 to nbd_pread(3) and similar to all zeroes, as set by nbd_set_pread_ini‐
648 tialize(3).
649 val set_strict_mode : t -> STRICT.t list -> unit
653 control how strictly to follow NBD protocol
655 By default, libnbd tries to detect requests that would trigger unde‐
657 fined behavior in the NBD protocol, and rejects them client side with‐
658 out causing any network traffic, rather than risking undefined server
659 behavior. However, for integration testing, it can be handy to relax
660 the strictness of libnbd, to coerce it into sending such requests over
661 the network for testing the robustness of the server in dealing with
662 such traffic.
663 The "flags" argument is a bitmask, including zero or more of the fol‐
665 lowing strictness flags:
666 "LIBNBD_STRICT_COMMANDS" = 1 If set, this flag rejects client requests
668 that do not comply with the set of advertised server flags (for exam‐
669 ple, attempting a write on a read-only server, or attempting to use
670 "LIBNBD_CMD_FLAG_FUA" when nbd_can_fua(3) returned false). If clear,
671 this flag relies on the server to reject unexpected commands.
672 "LIBNBD_STRICT_FLAGS" = 2 If set, this flag rejects client requests
674 that attempt to set a command flag not recognized by libnbd (those out‐
675 side of "LIBNBD_CMD_FLAG_MASK"), or a flag not normally associated with
676 a command (such as using "LIBNBD_CMD_FLAG_FUA" on a read command). If
677 clear, all flags are sent on to the server, even if sending such a flag
678 may cause the server to change its reply in a manner that confuses
679 libnbd, perhaps causing deadlock or ending the connection.
680 Flags that are known by libnbd as associated with a given command (such
682 as "LIBNBD_CMD_FLAG_DF" for nbd_pread_structured(3) gated by
683 nbd_can_df(3)) are controlled by "LIBNBD_STRICT_COMMANDS" instead.
684 Note that the NBD protocol only supports 16 bits of command flags, even
686 though the libnbd API uses "uint32_t"; bits outside of the range per‐
687 mitted by the protocol are always a client-side error.
688 "LIBNBD_STRICT_BOUNDS" = 3 If set, this flag rejects client requests
690 that would exceed the export bounds without sending any traffic to the
691 server. If clear, this flag relies on the server to detect
692 out-of-bounds requests.
693 "LIBNBD_STRICT_ZERO_SIZE" = 4 If set, this flag rejects client requests
695 with length 0. If clear, this permits zero-length requests to the
696 server, which may produce undefined results.
697 "LIBNBD_STRICT_ALIGN" = 5 If set, and the server provided minimum block
699 sizes (see nbd_get_block_size(3), this flag rejects client requests
700 that do not have length and offset aligned to the server's minimum re‐
701 quirements. If clear, unaligned requests are sent to the server, where
702 it is up to the server whether to honor or reject the request.
703 For convenience, the constant "LIBNBD_STRICT_MASK" is available to de‐
705 scribe all strictness flags supported by this build of libnbd. Future
706 versions of libnbd may add further flags, which are likely to be en‐
707 abled by default for additional client-side filtering. As such, when
708 attempting to relax only one specific bit while keeping remaining
709 checks at the client side, it is wiser to first call
710 nbd_get_strict_mode(3) and modify that value, rather than blindly set‐
711 ting a constant value.
712 val get_strict_mode : t -> STRICT.t list
716 see which strictness flags are in effect
718 Return flags indicating which protocol strictness items are being en‐
720 forced locally by libnbd rather than the server. The return value from
721 a newer library version may include bits that were undefined at the
722 time of compilation.
723 val set_opt_mode : t -> bool -> unit
727 control option mode, for pausing during option negotiation
729 Set this flag to true in order to request that a connection command
731 "nbd_connect_*" will pause for negotiation options rather than proceed‐
732 ing all the way to the ready state, when communicating with a newstyle
733 server. This setting has no effect when connecting to an oldstyle
734 server.
735 When option mode is enabled, you have fine-grained control over which
737 options are negotiated, compared to the default of the server negotiat‐
738 ing everything on your behalf using settings made before starting the
739 connection. To leave the mode and proceed on to the ready state, you
740 must use nbd_opt_go(3) successfully; a failed nbd_opt_go(3) returns to
741 the negotiating state to allow a change of export name before trying
742 again. You may also use nbd_opt_abort(3) to end the connection without
743 finishing negotiation.
744 val get_opt_mode : t -> bool
748 return whether option mode was enabled
750 Return true if option negotiation mode was enabled on this handle.
752 val opt_go : t -> unit
756 end negotiation and move on to using an export
758 Request that the server finish negotiation and move on to serving the
760 export previously specified by the most recent nbd_set_export_name(3)
761 or nbd_connect_uri(3). This can only be used if nbd_set_opt_mode(3)
762 enabled option mode.
763 If this fails, the server may still be in negotiation, where it is pos‐
765 sible to attempt another option such as a different export name; al‐
766 though older servers will instead have killed the connection.
767 val opt_abort : t -> unit
771 end negotiation and close the connection
773 Request that the server finish negotiation, gracefully if possible,
775 then close the connection. This can only be used if nbd_set_opt_mode(3)
776 enabled option mode.
777 val opt_list : t -> (string -> string -> int) -> int
781 request the server to list all exports during negotiation
783 Request that the server list all exports that it supports. This can
785 only be used if nbd_set_opt_mode(3) enabled option mode.
786 The "list" function is called once per advertised export, with any
788 "user_data" passed to this function, and with "name" and "description"
789 supplied by the server. Many servers omit descriptions, in which case
790 "description" will be an empty string. Remember that it is not safe to
791 call nbd_set_export_name(3) from within the context of the callback
792 function; rather, your code must copy any "name" needed for later use
793 after this function completes. At present, the return value of the
794 callback is ignored, although a return of -1 should be avoided.
795 For convenience, when this function succeeds, it returns the number of
797 exports that were advertised by the server.
798 Not all servers understand this request, and even when it is under‐
800 stood, the server might intentionally send an empty list to avoid being
801 an information leak, may encounter a failure after delivering partial
802 results, or may refuse to answer more than one query per connection in
803 the interest of avoiding negotiation that does not resolve. Thus, this
804 function may succeed even when no exports are reported, or may fail but
805 have a non-empty list. Likewise, the NBD protocol does not specify an
806 upper bound for the number of exports that might be advertised, so
807 client code should be aware that a server may send a lengthy list.
808 For nbd-server(1) you will need to allow clients to make list requests
810 by adding "allowlist=true" to the " generic " section of
811 /etc/nbd-server/config. For qemu-nbd(8), a description is set with
812 *-D*.
813 val opt_info : t -> unit
817 request the server for information about an export
819 Request that the server supply information about the export name previ‐
821 ously specified by the most recent nbd_set_export_name(3) or nbd_con‐
822 nect_uri(3). This can only be used if nbd_set_opt_mode(3) enabled op‐
823 tion mode.
824 If successful, functions like nbd_is_read_only(3) and nbd_get_size(3)
826 will report details about that export. In general, if nbd_opt_go(3) is
827 called next, that call will likely succeed with the details remaining
828 the same, although this is not guaranteed by all servers.
829 Not all servers understand this request, and even when it is under‐
831 stood, the server might fail the request even when a corresponding
832 nbd_opt_go(3) would succeed.
833 val opt_list_meta_context : t -> (string -> int) -> int
837 request the server to list available meta contexts
839 Request that the server list available meta contexts associated with
841 the export previously specified by the most recent nbd_set_ex‐
842 port_name(3) or nbd_connect_uri(3). This can only be used if
843 nbd_set_opt_mode(3) enabled option mode.
844 The NBD protocol allows a client to decide how many queries to ask the
846 server. Rather than taking that list of queries as a parameter to this
847 function, libnbd reuses the current list of requested meta contexts as
848 set by nbd_add_meta_context(3); you can use nbd_clear_meta_contexts(3)
849 to set up a different list of queries. When the list is empty, a server
850 will typically reply with all contexts that it supports; when the list
851 is non-empty, the server will reply only with supported contexts that
852 match the client's request. Note that a reply by the server might be
853 encoded to represent several feasible contexts within one string,
854 rather than multiple strings per actual context name that would actu‐
855 ally succeed during nbd_opt_go(3); so it is still necessary to use
856 nbd_can_meta_context(3) after connecting to see which contexts are ac‐
857 tually supported.
858 The "context" function is called once per server reply, with any
860 "user_data" passed to this function, and with "name" supplied by the
861 server. Remember that it is not safe to call nbd_add_meta_context(3)
862 from within the context of the callback function; rather, your code
863 must copy any "name" needed for later use after this function com‐
864 pletes. At present, the return value of the callback is ignored, al‐
865 though a return of -1 should be avoided.
866 For convenience, when this function succeeds, it returns the number of
868 replies returned by the server.
869 Not all servers understand this request, and even when it is under‐
871 stood, the server might intentionally send an empty list because it
872 does not support the requested context, or may encounter a failure af‐
873 ter delivering partial results. Thus, this function may succeed even
874 when no contexts are reported, or may fail but have a non-empty list.
875 Likewise, the NBD protocol does not specify an upper bound for the num‐
876 ber of replies that might be advertised, so client code should be aware
877 that a server may send a lengthy list.
878 val add_meta_context : t -> string -> unit
882 ask server to negotiate metadata context
884 During connection libnbd can negotiate zero or more metadata contexts
886 with the server. Metadata contexts are features (such as "base:alloca‐
887 tion") which describe information returned by the nbd_block_status(3)
888 command (for "base:allocation" this is whether blocks of data are allo‐
889 cated, zero or sparse).
890 This call adds one metadata context to the list to be negotiated. You
892 can call it as many times as needed. The list is initially empty when
893 the handle is created; you can check the contents of the list with
894 nbd_get_nr_meta_contexts(3) and nbd_get_meta_context(3), or clear it
895 with nbd_clear_meta_contexts(3).
896 The NBD protocol limits meta context names to 4096 bytes, but servers
898 may not support the full length. The encoding of meta context names is
899 always UTF-8.
900 Not all servers support all metadata contexts. To learn if a context
902 was actually negotiated, call nbd_can_meta_context(3) after connecting.
903 The single parameter is the name of the metadata context, for example
905 "LIBNBD_CONTEXT_BASE_ALLOCATION". <libnbd.h> includes defined con‐
906 stants beginning with "LIBNBD_CONTEXT_" for some well-known contexts,
907 but you are free to pass in other contexts.
908 Other metadata contexts are server-specific, but include
910 "qemu:dirty-bitmap:..." and "qemu:allocation-depth" for qemu-nbd (see
911 qemu-nbd *-B* and *-A* options).
912 val get_nr_meta_contexts : t -> int
916 return the current number of requested meta contexts
918 During connection libnbd can negotiate zero or more metadata contexts
920 with the server. Metadata contexts are features (such as "base:alloca‐
921 tion") which describe information returned by the nbd_block_status(3)
922 command (for "base:allocation" this is whether blocks of data are allo‐
923 cated, zero or sparse).
924 This command returns how many meta contexts have been added to the list
926 to request from the server via nbd_add_meta_context(3). The server is
927 not obligated to honor all of the requests; to see what it actually
928 supports, see nbd_can_meta_context(3).
929 val get_meta_context : t -> int -> string
933 return the i'th meta context request
935 During connection libnbd can negotiate zero or more metadata contexts
937 with the server. Metadata contexts are features (such as "base:alloca‐
938 tion") which describe information returned by the nbd_block_status(3)
939 command (for "base:allocation" this is whether blocks of data are allo‐
940 cated, zero or sparse).
941 This command returns the i'th meta context request, as added by
943 nbd_add_meta_context(3), and bounded by nbd_get_nr_meta_contexts(3).
944 val clear_meta_contexts : t -> unit
948 reset the list of requested meta contexts
950 During connection libnbd can negotiate zero or more metadata contexts
952 with the server. Metadata contexts are features (such as "base:alloca‐
953 tion") which describe information returned by the nbd_block_status(3)
954 command (for "base:allocation" this is whether blocks of data are allo‐
955 cated, zero or sparse).
956 This command resets the list of meta contexts to request back to an
958 empty list, for re-population by further use of nbd_add_meta_con‐
959 text(3). It is primarily useful when option negotiation mode is se‐
960 lected (see nbd_set_opt_mode(3)), for altering the list of attempted
961 contexts between subsequent export queries.
962 val set_uri_allow_transports : t -> ALLOW_TRANSPORT.t list -> unit
966 set the allowed transports in NBD URIs
968 Set which transports are allowed to appear in NBD URIs. The default is
970 to allow any transport.
971 The "mask" parameter may contain any of the following flags ORed to‐
973 gether:
974 "LIBNBD_ALLOW_TRANSPORT_TCP" "LIBNBD_ALLOW_TRANSPORT_UNIX" "LIBNBD_AL‐
976 LOW_TRANSPORT_VSOCK"
977 For convenience, the constant "LIBNBD_ALLOW_TRANSPORT_MASK" is avail‐
979 able to describe all transports recognized by this build of libnbd. A
980 future version of the library may add new flags.
981 val set_uri_allow_tls : t -> TLS.t -> unit
985 set the allowed TLS settings in NBD URIs
987 Set which TLS settings are allowed to appear in NBD URIs. The default
989 is to allow either non-TLS or TLS URIs.
990 The "tls" parameter can be:
992 "LIBNBD_TLS_DISABLE" TLS URIs are not permitted, ie. a URI such as
994 "nbds://..." will be rejected.
995 "LIBNBD_TLS_ALLOW" This is the default. TLS may be used or not, depend‐
997 ing on whether the URI uses "nbds" or "nbd".
998 "LIBNBD_TLS_REQUIRE" TLS URIs are required. All URIs must use "nbds".
1000 val set_uri_allow_local_file : t -> bool -> unit
1004 set the allowed transports in NBD URIs
1006 Allow NBD URIs to reference local files. This is *disabled* by default.
1008 Currently this setting only controls whether the "tls-psk-file" parame‐
1010 ter in NBD URIs is allowed.
1011 val connect_uri : t -> string -> unit
1015 connect to NBD URI
1017 Connect (synchronously) to an NBD server and export by specifying the
1019 NBD URI. This call parses the URI and calls nbd_set_export_name(3) and
1020 nbd_set_tls(3) and other calls as needed, followed by nbd_con‐
1021 nect_tcp(3) or nbd_connect_unix(3).
1022 This call returns when the connection has been made.
1024 Example URIs supported "nbd://example.com" Connect over TCP, unen‐
1026 crypted, to "example.com" port 10809.
1027 "nbds://example.com" Connect over TCP with TLS, to "example.com" port
1029 10809. If the server does not support TLS then this will fail.
1030 "nbd+unix:///foo?socket=/tmp/nbd.sock" Connect over the Unix domain
1032 socket /tmp/nbd.sock to an NBD server running locally. The export name
1033 is set to "foo" (note without any leading "/" character).
1034 "nbds+unix://alice@/?socket=/tmp/nbd.sock&tls-certificat es=certs" Con‐
1036 nect over a Unix domain socket, enabling TLS and setting the path to a
1037 directory containing certificates and keys.
1038 "nbd+vsock:///" In this scenario libnbd is running in a virtual ma‐
1040 chine. Connect over "AF_VSOCK" to an NBD server running on the hypervi‐
1041 sor.
1042 Supported URI formats The following schemes are supported in the cur‐
1044 rent version of libnbd:
1045 "nbd:" Connect over TCP without using TLS.
1047 "nbds:" Connect over TCP. TLS is required and the connection will fail
1049 if the server does not support TLS.
1050 "nbd+unix:" "nbds+unix:" Connect over a Unix domain socket, without or
1052 with TLS respectively. The "socket" parameter is required.
1053 "nbd+vsock:" "nbds+vsock:" Connect over the "AF_VSOCK" transport, with‐
1055 out or with TLS respectively.
1056 The authority part of the URI (" username@ servername :port ") is
1058 parsed depending on the transport. For TCP it specifies the server to
1059 connect to and optional port number. For "+unix" it should not be
1060 present. For "+vsock" the server name is the numeric CID (eg. 2 to con‐
1061 nect to the host), and the optional port number may be present. If the
1062 "username" is present it is used for TLS authentication.
1063 For all transports, an export name may be present, parsed in accordance
1065 with the NBD URI specification.
1066 Finally the query part of the URI can contain:
1068 socket=SOCKET Specifies the Unix domain socket to connect on. Must be
1070 present for the "+unix" transport and must not be present for the other
1071 transports.
1072 tls-certificates=DIR Set the certificates directory. See
1074 nbd_set_tls_certificates(3). Note this is not allowed by default - see
1075 next section.
1076 tls-psk-file=PSKFILE Set the PSK file. See nbd_set_tls_psk_file(3).
1078 Note this is not allowed by default - see next section.
1079 Disable URI features For security reasons you might want to disable
1081 certain URI features. Pre-filtering URIs is error-prone and should not
1082 be attempted. Instead use the libnbd APIs below to control what can ap‐
1083 pear in URIs. Note you must call these functions on the same handle be‐
1084 fore calling nbd_connect_uri(3) or nbd_aio_connect_uri(3).
1085 TCP, Unix domain socket or "AF_VSOCK" transports Default: all allowed
1087 To select which transports are allowed call nbd_set_uri_allow_trans‐
1089 ports(3).
1090 TLS Default: both non-TLS and TLS connections allowed
1092 To force TLS off or on in URIs call nbd_set_uri_allow_tls(3).
1094 Connect to Unix domain socket in the local filesystem Default: allowed
1096 To prevent this you must disable the "+unix" transport using
1098 nbd_set_uri_allow_transports(3).
1099 Read from local files Default: denied
1101 To allow URIs to contain references to local files (eg. for parameters
1103 like "tls-psk-file") call nbd_set_uri_allow_local_file(3).
1104 Overriding the export name It is possible to override the export name
1106 portion of a URI by using nbd_set_opt_mode(3) to enable option mode,
1107 then using nbd_set_export_name(3) and nbd_opt_go(3) as part of subse‐
1108 quent negotiation.
1109 Optional features This call will fail if libnbd was not compiled with
1111 libxml2; you can test whether this is the case with nbd_sup‐
1112 ports_uri(3).
1113 Support for URIs that require TLS will fail if libnbd was not compiled
1115 with gnutls; you can test whether this is the case with nbd_sup‐
1116 ports_tls(3).
1117 Constructing a URI from an existing connection See nbd_get_uri(3).
1119 val connect_unix : t -> string -> unit
1123 connect to NBD server over a Unix domain socket
1125 Connect (synchronously) over the named Unix domain socket ("unix‐
1127 socket") to an NBD server running on the same machine. This call re‐
1128 turns when the connection has been made.
1129 val connect_vsock : t -> int64 -> int64 -> unit
1133 connect to NBD server over AF_VSOCK protocol
1135 Connect (synchronously) over the "AF_VSOCK" protocol from a virtual ma‐
1137 chine to an NBD server, usually running on the host. The "cid" and
1138 "port" parameters specify the server address. Usually "cid" should be 2
1139 (to connect to the host), and "port" might be 10809 or another port
1140 number assigned to you by the host administrator. This call returns
1141 when the connection has been made.
1142 val connect_tcp : t -> string -> string -> unit
1146 connect to NBD server over a TCP port
1148 Connect (synchronously) to the NBD server listening on "hostname:port".
1150 The "port" may be a port name such as "nbd", or it may be a port number
1151 as a string such as "10809". This call returns when the connection has
1152 been made.
1153 val connect_socket : t -> Unix.file_descr -> unit
1157 connect directly to a connected socket
1159 Pass a connected socket "sock" through which libnbd will talk to the
1161 NBD server.
1162 The caller is responsible for creating and connecting this socket by
1164 some method, before passing it to libnbd.
1165 If this call returns without error then socket ownership is passed to
1167 libnbd. Libnbd will close the socket when the handle is closed. The
1168 caller must not use the socket in any way.
1169 val connect_command : t -> string list -> unit
1173 connect to NBD server command
1175 Run the command as a subprocess and connect to it over stdin/stdout.
1177 This is for use with NBD servers which can behave like inetd clients,
1178 such as nbdkit(1) using the *-s*/*--single* flag, and nbd-server(1)
1179 with port number set to 0.
1180 To run qemu-nbd(1), use nbd_connect_systemd_socket_activation(3) in‐
1182 stead.
1183 Subprocess Libnbd will fork the "argv" command and pass the NBD socket
1185 to it using file descriptors 0 and 1 (stdin/stdout):
1186 ┌─────────┬─────────┐ ┌────────────────┐ │ program │ libnbd │ │
1188 NBD server │ │ │ │ │ (argv) │ │ │
1189 socket ╍╍╍╍╍╍╍╍▶ stdin/stdout │ └─────────┴─────────┘
1190 └────────────────┘
1191 When the NBD handle is closed the server subprocess is killed.
1193 val connect_systemd_socket_activation : t -> string list -> unit
1197 connect using systemd socket activation
1199 Run the command as a subprocess and connect to it using systemd socket
1201 activation.
1202 This is especially useful for running qemu-nbd(1) as a subprocess of
1204 libnbd, for example to use it to open qcow2 files.
1205 To run nbdkit as a subprocess, this function can be used, or nbd_con‐
1207 nect_command(3).
1208 To run nbd-server(1) as a subprocess, this function cannot be used, you
1210 must use nbd_connect_command(3).
1211 Socket activation Libnbd will fork the "argv" command and pass an NBD
1213 socket to it using special "LISTEN_*" environment variables (as defined
1214 by the systemd socket activation protocol).
1215 ┌─────────┬─────────┐ ┌───────────────┐ │ program │ libnbd │ │
1217 qemu-nbd or │ │ │ │ │ other server │ │ │
1218 socket ╍╍╍╍╍╍╍╍▶ │ └─────────┴─────────┘
1219 └───────────────┘
1220 When the NBD handle is closed the server subprocess is killed.
1222 val is_read_only : t -> bool
1226 is the NBD export read-only?
1228 Returns true if the NBD export is read-only; writes and write-like op‐
1230 erations will fail.
1231 This call does not block, because it returns data that is saved in the
1233 handle from the NBD protocol handshake.
1234 val can_flush : t -> bool
1238 does the server support the flush command?
1240 Returns true if the server supports the flush command (see
1242 nbd_flush(3), nbd_aio_flush(3)). Returns false if the server does not.
1243 This call does not block, because it returns data that is saved in the
1245 handle from the NBD protocol handshake.
1246 val can_fua : t -> bool
1250 does the server support the FUA flag?
1252 Returns true if the server supports the FUA flag on certain commands
1254 (see nbd_pwrite(3)).
1255 This call does not block, because it returns data that is saved in the
1257 handle from the NBD protocol handshake.
1258 val is_rotational : t -> bool
1262 is the NBD disk rotational (like a disk)?
1264 Returns true if the disk exposed over NBD is rotational (like a tradi‐
1266 tional floppy or hard disk). Returns false if the disk has no penalty
1267 for random access (like an SSD or RAM disk).
1268 This call does not block, because it returns data that is saved in the
1270 handle from the NBD protocol handshake.
1271 val can_trim : t -> bool
1275 does the server support the trim command?
1277 Returns true if the server supports the trim command (see nbd_trim(3),
1279 nbd_aio_trim(3)). Returns false if the server does not.
1280 This call does not block, because it returns data that is saved in the
1282 handle from the NBD protocol handshake.
1283 val can_zero : t -> bool
1287 does the server support the zero command?
1289 Returns true if the server supports the zero command (see nbd_zero(3),
1291 nbd_aio_zero(3)). Returns false if the server does not.
1292 This call does not block, because it returns data that is saved in the
1294 handle from the NBD protocol handshake.
1295 val can_fast_zero : t -> bool
1299 does the server support the fast zero flag?
1301 Returns true if the server supports the use of the
1303 "LIBNBD_CMD_FLAG_FAST_ZERO" flag to the zero command (see nbd_zero(3),
1304 nbd_aio_zero(3)). Returns false if the server does not.
1305 This call does not block, because it returns data that is saved in the
1307 handle from the NBD protocol handshake.
1308 val can_df : t -> bool
1312 does the server support the don't fragment flag to pread?
1314 Returns true if the server supports structured reads with an ability to
1316 request a non-fragmented read (see nbd_pread_structured(3),
1317 nbd_aio_pread_structured(3)). Returns false if the server either lacks
1318 structured reads or if it does not support a non-fragmented read re‐
1319 quest.
1320 This call does not block, because it returns data that is saved in the
1322 handle from the NBD protocol handshake.
1323 val can_multi_conn : t -> bool
1327 does the server support multi-conn?
1329 Returns true if the server supports multi-conn. Returns false if the
1331 server does not.
1332 It is not safe to open multiple handles connecting to the same server
1334 if you will write to the server and the server does not advertise
1335 multi-conn support. The safe way to check for this is to open one con‐
1336 nection, check this flag is true, then open further connections as re‐
1337 quired.
1338 This call does not block, because it returns data that is saved in the
1340 handle from the NBD protocol handshake.
1341 val can_cache : t -> bool
1345 does the server support the cache command?
1347 Returns true if the server supports the cache command (see
1349 nbd_cache(3), nbd_aio_cache(3)). Returns false if the server does not.
1350 This call does not block, because it returns data that is saved in the
1352 handle from the NBD protocol handshake.
1353 val can_meta_context : t -> string -> bool
1357 does the server support a specific meta context?
1359 Returns true if the server supports the given meta context (see
1361 nbd_add_meta_context(3)). Returns false if the server does not.
1362 The single parameter is the name of the metadata context, for example
1364 "LIBNBD_CONTEXT_BASE_ALLOCATION". <libnbd.h> includes defined con‐
1365 stants for well-known namespace contexts beginning with "LIBNBD_CON‐
1366 TEXT_", but you are free to pass in other contexts.
1367 This call does not block, because it returns data that is saved in the
1369 handle from the NBD protocol handshake.
1370 val get_protocol : t -> string
1374 return the NBD protocol variant
1376 Return the NBD protocol variant in use on the connection. At the moment
1378 this returns one of the strings "oldstyle", "newstyle" or "new‐
1379 style-fixed". Other strings might be returned in the future. Most mod‐
1380 ern NBD servers use "newstyle-fixed".
1381 This call does not block, because it returns data that is saved in the
1383 handle from the NBD protocol handshake.
1384 val get_size : t -> int64
1388 return the export size
1390 Returns the size in bytes of the NBD export.
1392 This call does not block, because it returns data that is saved in the
1394 handle from the NBD protocol handshake.
1395 val get_block_size : t -> SIZE.t -> int64
1399 return a specific server block size constraint
1401 Returns a specific size constraint advertised by the server, if any. If
1403 the return is zero, the server did not advertise a constraint.
1404 "size_type" must be one of the following constraints:
1405 "LIBNBD_SIZE_MINIMUM" = 0 If non-zero, this will be a power of 2 be‐
1407 tween 1 and 64k; any client request that is not aligned in length or
1408 offset to this size is likely to fail with "EINVAL". The image size
1409 will generally also be a multiple of this value (if not, the final few
1410 bytes are inaccessible while obeying alignment constraints). If zero,
1411 it is safest to assume a minimum block size of 512, although many
1412 servers support a minimum block size of 1. If the server provides a
1413 constraint, then libnbd defaults to honoring that constraint
1414 client-side unless "LIBNBD_STRICT_ALIGN" is cleared in
1415 nbd_set_strict_mode(3).
1416 "LIBNBD_SIZE_PREFERRED" = 1 If non-zero, this is a power of 2 repre‐
1418 senting the preferred size for efficient I/O. Smaller requests may in‐
1419 cur overhead such as read-modify-write cycles that will not be present
1420 when using I/O that is a multiple of this value. This value may be
1421 larger than the size of the export. If zero, using 4k as a preferred
1422 block size tends to give decent performance.
1423 "LIBNBD_SIZE_MAXIMUM" = 2 If non-zero, this represents the maximum
1425 length that the server is willing to handle during nbd_pread(3) or
1426 nbd_pwrite(3). Other functions like nbd_zero(3) may still be able to
1427 use larger sizes. Note that this function returns what the server ad‐
1428 vertised, but libnbd itself imposes a maximum of 64M. If zero, some NBD
1429 servers will abruptly disconnect if a transaction involves more than
1430 32M.
1431 Future NBD extensions may result in additional "size_type" values. Note
1433 that by default, libnbd requests all available block sizes, but that a
1434 server may differ in what sizes it chooses to report if nbd_set_re‐
1435 quest_block_size(3) alters whether the client requests sizes.
1436 This call does not block, because it returns data that is saved in the
1438 handle from the NBD protocol handshake.
1439 val pread : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 -> unit
1443 read from the NBD server
1445 Issue a read command to the NBD server for the range starting at "off‐
1447 set" and ending at "offset" + "count" - 1. NBD can only read all or
1448 nothing using this call. The call returns when the data has been read
1449 fully into "buf" or there is an error. See also nbd_pread_struc‐
1450 tured(3), if finer visibility is required into the server's replies, or
1451 if you want to use "LIBNBD_CMD_FLAG_DF".
1452 Note that libnbd currently enforces a maximum read buffer of 64MiB,
1454 even if the server would permit a larger buffer in a single transac‐
1455 tion; attempts to exceed this will result in an "ERANGE" error. The
1456 server may enforce a smaller limit, which can be learned with
1457 nbd_get_block_size(3).
1458 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
1460 tocol extensions).
1461 Note that if this command fails, and nbd_get_pread_initialize(3) re‐
1463 turns true, then libnbd sanitized "buf", but it is unspecified whether
1464 the contents of "buf" will read as zero or as partial results from the
1465 server. If nbd_get_pread_initialize(3) returns false, then libnbd did
1466 not sanitize "buf", and the contents are undefined on failure.
1467 By default, libnbd will reject attempts to use this function with pa‐
1469 rameters that are likely to result in server failure, such as request‐
1470 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1471 used to alter which scenarios should await a server reply rather than
1472 failing fast.
1473 val pread_structured : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 ->
1477 (bytes -> int64 -> int -> int Stdlib.ref -> int) -> unit
1478 read from the NBD server
1480 Issue a read command to the NBD server for the range starting at "off‐
1482 set" and ending at "offset" + "count" - 1. The server's response may be
1483 subdivided into chunks which may arrive out of order before reassembly
1484 into the original buffer; the "chunk" callback is used for notification
1485 after each chunk arrives, and may perform additional sanity checking on
1486 the server's reply. The callback cannot call "nbd_*" APIs on the same
1487 handle since it holds the handle lock and will cause a deadlock. If the
1488 callback returns -1, and no earlier error has been detected, then the
1489 overall read command will fail with any non-zero value stored into the
1490 callback's "error" parameter (with a default of "EPROTO"); but any fur‐
1491 ther chunks will still invoke the callback.
1492 The "chunk" function is called once per chunk of data received, with
1494 the "user_data" passed to this function. The "subbuf" and "count" pa‐
1495 rameters represent the subset of the original buffer which has just
1496 been populated by results from the server (in C, "subbuf" always points
1497 within the original "buf"; but this guarantee may not extend to other
1498 language bindings). The "offset" parameter represents the absolute off‐
1499 set at which "subbuf" begins within the image (note that this is not
1500 the relative offset of "subbuf" within the original buffer "buf").
1501 Changes to "error" on output are ignored unless the callback fails. The
1502 input meaning of the "error" parameter is controlled by the "status"
1503 parameter, which is one of
1504 "LIBNBD_READ_DATA" = 1 "subbuf" was populated with "count" bytes of
1506 data. On input, "error" contains the errno value of any earlier de‐
1507 tected error, or zero.
1508 "LIBNBD_READ_HOLE" = 2 "subbuf" represents a hole, and contains "count"
1510 NUL bytes. On input, "error" contains the errno value of any earlier
1511 detected error, or zero.
1512 "LIBNBD_READ_ERROR" = 3 "count" is 0, so "subbuf" is unusable. On in‐
1514 put, "error" contains the errno value reported by the server as occur‐
1515 ring while reading that "offset", regardless if any earlier error has
1516 been detected.
1517 Future NBD extensions may permit other values for "status", but those
1519 will not be returned to a client that has not opted in to requesting
1520 such extensions. If the server is non-compliant, it is possible for the
1521 "chunk" function to be called more times than you expect or with
1522 "count" 0 for "LIBNBD_READ_DATA" or "LIBNBD_READ_HOLE". It is also pos‐
1523 sible that the "chunk" function is not called at all (in particular,
1524 "LIBNBD_READ_ERROR" is used only when an error is associated with a
1525 particular offset, and not when the server reports a generic error),
1526 but you are guaranteed that the callback was called at least once if
1527 the overall read succeeds. Libnbd does not validate that the server
1528 obeyed the requirement that a read call must not have overlapping
1529 chunks and must not succeed without enough chunks to cover the entire
1530 request.
1531 Note that libnbd currently enforces a maximum read buffer of 64MiB,
1533 even if the server would permit a larger buffer in a single transac‐
1534 tion; attempts to exceed this will result in an "ERANGE" error. The
1535 server may enforce a smaller limit, which can be learned with
1536 nbd_get_block_size(3).
1537 The "flags" parameter may be 0 for no flags, or may contain
1539 "LIBNBD_CMD_FLAG_DF" meaning that the server should not reply with more
1540 than one fragment (if that is supported - some servers cannot do this,
1541 see nbd_can_df(3)). Libnbd does not validate that the server actually
1542 obeys the flag.
1543 Note that if this command fails, and nbd_get_pread_initialize(3) re‐
1545 turns true, then libnbd sanitized "buf", but it is unspecified whether
1546 the contents of "buf" will read as zero or as partial results from the
1547 server. If nbd_get_pread_initialize(3) returns false, then libnbd did
1548 not sanitize "buf", and the contents are undefined on failure.
1549 By default, libnbd will reject attempts to use this function with pa‐
1551 rameters that are likely to result in server failure, such as request‐
1552 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1553 used to alter which scenarios should await a server reply rather than
1554 failing fast.
1555 val pwrite : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 -> unit
1559 write to the NBD server
1561 Issue a write command to the NBD server, writing the data in "buf" to
1563 the range starting at "offset" and ending at "offset" + "count" - 1.
1564 NBD can only write all or nothing using this call. The call returns
1565 when the command has been acknowledged by the server, or there is an
1566 error. Note this will generally return an error if nbd_is_read_only(3)
1567 is true.
1568 Note that libnbd currently enforces a maximum write buffer of 64MiB,
1570 even if the server would permit a larger buffer in a single transac‐
1571 tion; attempts to exceed this will result in an "ERANGE" error. The
1572 server may enforce a smaller limit, which can be learned with
1573 nbd_get_block_size(3).
1574 The "flags" parameter may be 0 for no flags, or may contain
1576 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
1577 the data has been committed to permanent storage (if that is supported
1578 - some servers cannot do this, see nbd_can_fua(3)).
1579 By default, libnbd will reject attempts to use this function with pa‐
1581 rameters that are likely to result in server failure, such as request‐
1582 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1583 used to alter which scenarios should await a server reply rather than
1584 failing fast.
1585 val shutdown : ?flags:SHUTDOWN.t list -> t -> unit
1589 disconnect from the NBD server
1591 Issue the disconnect command to the NBD server. This is a nice way to
1593 tell the server we are going away, but from the client's point of view
1594 has no advantage over abruptly closing the connection (see
1595 nbd_close(3)).
1596 This function works whether or not the handle is ready for transmission
1598 of commands. If more fine-grained control is needed, see nbd_aio_dis‐
1599 connect(3).
1600 The "flags" argument is a bitmask, including zero or more of the fol‐
1602 lowing shutdown flags:
1603 "LIBNBD_SHUTDOWN_ABANDON_PENDING" = 0x10000 If there are any pending
1605 requests which have not yet been sent to the server (see
1606 nbd_aio_in_flight(3)), abandon them without sending them to the server,
1607 rather than the usual practice of issuing those commands before inform‐
1608 ing the server of the intent to disconnect.
1609 For convenience, the constant "LIBNBD_SHUTDOWN_MASK" is available to
1611 describe all shutdown flags recognized by this build of libnbd. A fu‐
1612 ture version of the library may add new flags.
1613 val flush : ?flags:CMD_FLAG.t list -> t -> unit
1617 send flush command to the NBD server
1619 Issue the flush command to the NBD server. The function should return
1621 when all write commands which have completed have been committed to
1622 permanent storage on the server. Note this will generally return an er‐
1623 ror if nbd_can_flush(3) is false.
1624 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
1626 tocol extensions).
1627 By default, libnbd will reject attempts to use this function with pa‐
1629 rameters that are likely to result in server failure, such as request‐
1630 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1631 used to alter which scenarios should await a server reply rather than
1632 failing fast.
1633 val trim : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
1637 send trim command to the NBD server
1639 Issue a trim command to the NBD server, which if supported by the
1641 server causes a hole to be punched in the backing store starting at
1642 "offset" and ending at "offset" + "count" - 1. The call returns when
1643 the command has been acknowledged by the server, or there is an error.
1644 Note this will generally return an error if nbd_can_trim(3) is false or
1645 nbd_is_read_only(3) is true.
1646 Note that not all servers can support a "count" of 4GiB or larger. The
1648 NBD protocol does not yet have a way for a client to learn if the
1649 server will enforce an even smaller maximum trim size, although a fu‐
1650 ture extension may add a constraint visible in nbd_get_block_size(3).
1651 The "flags" parameter may be 0 for no flags, or may contain
1653 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
1654 the data has been committed to permanent storage (if that is supported
1655 - some servers cannot do this, see nbd_can_fua(3)).
1656 By default, libnbd will reject attempts to use this function with pa‐
1658 rameters that are likely to result in server failure, such as request‐
1659 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1660 used to alter which scenarios should await a server reply rather than
1661 failing fast.
1662 val cache : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
1666 send cache (prefetch) command to the NBD server
1668 Issue the cache (prefetch) command to the NBD server, which if sup‐
1670 ported by the server causes data to be prefetched into faster storage
1671 by the server, speeding up a subsequent nbd_pread(3) call. The server
1672 can also silently ignore this command. Note this will generally return
1673 an error if nbd_can_cache(3) is false.
1674 Note that not all servers can support a "count" of 4GiB or larger. The
1676 NBD protocol does not yet have a way for a client to learn if the
1677 server will enforce an even smaller maximum cache size, although a fu‐
1678 ture extension may add a constraint visible in nbd_get_block_size(3).
1679 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
1681 tocol extensions).
1682 By default, libnbd will reject attempts to use this function with pa‐
1684 rameters that are likely to result in server failure, such as request‐
1685 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1686 used to alter which scenarios should await a server reply rather than
1687 failing fast.
1688 val zero : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
1692 send write zeroes command to the NBD server
1694 Issue a write zeroes command to the NBD server, which if supported by
1696 the server causes a zeroes to be written efficiently starting at "off‐
1697 set" and ending at "offset"
1698 -"count" - 1. The call returns when the command has been acknowledged
1700 by the server, or there is an error. Note this will generally return
1701 an error if nbd_can_zero(3) is false or nbd_is_read_only(3) is true.
1702 Note that not all servers can support a "count" of 4GiB or larger. The
1704 NBD protocol does not yet have a way for a client to learn if the
1705 server will enforce an even smaller maximum zero size, although a fu‐
1706 ture extension may add a constraint visible in nbd_get_block_size(3).
1707 Also, some servers may permit a larger zero request only when the
1708 "LIBNBD_CMD_FLAG_FAST_ZERO" is in use.
1709 The "flags" parameter may be 0 for no flags, or may contain
1711 "LIBNBD_CMD_FLAG_FUA" meaning that the server should not return until
1712 the data has been committed to permanent storage (if that is supported
1713 - some servers cannot do this, see nbd_can_fua(3)),
1714 "LIBNBD_CMD_FLAG_NO_HOLE" meaning that the server should favor writing
1715 actual allocated zeroes over punching a hole, and/or
1716 "LIBNBD_CMD_FLAG_FAST_ZERO" meaning that the server must fail quickly
1717 if writing zeroes is no faster than a normal write (if that is sup‐
1718 ported - some servers cannot do this, see nbd_can_fast_zero(3)).
1719 By default, libnbd will reject attempts to use this function with pa‐
1721 rameters that are likely to result in server failure, such as request‐
1722 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1723 used to alter which scenarios should await a server reply rather than
1724 failing fast.
1725 val block_status : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 ->
1729 (string -> int64 -> int64 array -> int Stdlib.ref -> int) -> unit
1730 send block status command to the NBD server
1732 Issue the block status command to the NBD server. If supported by the
1734 server, this causes metadata context information about blocks beginning
1735 from the specified offset to be returned. The "count" parameter is a
1736 hint: the server may choose to return less status, or the final block
1737 may extend beyond the requested range. If multiple contexts are sup‐
1738 ported, the number of blocks and cumulative length of those blocks need
1739 not be identical between contexts.
1740 Note that not all servers can support a "count" of 4GiB or larger. The
1742 NBD protocol does not yet have a way for a client to learn if the
1743 server will enforce an even smaller maximum block status size, although
1744 a future extension may add a constraint visible in
1745 nbd_get_block_size(3).
1746 Depending on which metadata contexts were enabled before connecting
1748 (see nbd_add_meta_context(3)) and which are supported by the server
1749 (see nbd_can_meta_context(3)) this call returns information about ex‐
1750 tents by calling back to the "extent" function. The callback cannot
1751 call "nbd_*" APIs on the same handle since it holds the handle lock and
1752 will cause a deadlock. If the callback returns -1, and no earlier error
1753 has been detected, then the overall block status command will fail with
1754 any non-zero value stored into the callback's "error" parameter (with a
1755 default of "EPROTO"); but any further contexts will still invoke the
1756 callback.
1757 The "extent" function is called once per type of metadata available,
1759 with the "user_data" passed to this function. The "metacontext" parame‐
1760 ter is a string such as "base:allocation". The "entries" array is an
1761 array of pairs of integers with the first entry in each pair being the
1762 length (in bytes) of the block and the second entry being a sta‐
1763 tus/flags field which is specific to the metadata context. (The number
1764 of pairs passed to the function is "nr_entries/2".) The NBD protocol
1765 document in the section about "NBD_REPLY_TYPE_BLOCK_STATUS" describes
1766 the meaning of this array; for contexts known to libnbd, <libnbd.h>
1767 contains constants beginning with "LIBNBD_STATE_" that may help deci‐
1768 pher the values. On entry to the callback, the "error" parameter con‐
1769 tains the errno value of any previously detected error, but even if an
1770 earlier error was detected, the current "metacontext" and "entries" are
1771 valid.
1772 It is possible for the extent function to be called more times than you
1774 expect (if the server is buggy), so always check the "metacontext"
1775 field to ensure you are receiving the data you expect. It is also pos‐
1776 sible that the extent function is not called at all, even for metadata
1777 contexts that you requested. This indicates either that the server
1778 doesn't support the context or for some other reason cannot return the
1779 data.
1780 The "flags" parameter may be 0 for no flags, or may contain
1782 "LIBNBD_CMD_FLAG_REQ_ONE" meaning that the server should return only
1783 one extent per metadata context where that extent does not exceed
1784 "count" bytes; however, libnbd does not validate that the server obeyed
1785 the flag.
1786 By default, libnbd will reject attempts to use this function with pa‐
1788 rameters that are likely to result in server failure, such as request‐
1789 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1790 used to alter which scenarios should await a server reply rather than
1791 failing fast.
1792 val poll : t -> int -> int
1796 poll the handle once
1798 This is a simple implementation of poll(2) which is used internally by
1800 synchronous API calls. On success, it returns 0 if the "timeout" (in
1801 milliseconds) occurs, or 1 if the poll completed and the state machine
1802 progressed. Set "timeout" to -1 to block indefinitely (but be careful
1803 that eventual action is actually expected - for example, if the connec‐
1804 tion is established but there are no commands in flight, using an infi‐
1805 nite timeout will permanently block).
1806 This function is mainly useful as an example of how you might integrate
1808 libnbd with your own main loop, rather than being intended as something
1809 you would use.
1810 val aio_connect : t -> string -> unit
1814 connect to the NBD server
1816 Begin connecting to the NBD server. The "addr" and "addrlen" parameters
1818 specify the address of the socket to connect to.
1819 You can check if the connection is still connecting by calling
1821 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1822 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1823 tion.
1824 val aio_connect_uri : t -> string -> unit
1828 connect to an NBD URI
1830 Begin connecting to the NBD URI "uri". Parameters behave as documented
1832 in nbd_connect_uri(3).
1833 You can check if the connection is still connecting by calling
1835 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1836 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1837 tion.
1838 val aio_connect_unix : t -> string -> unit
1842 connect to the NBD server over a Unix domain socket
1844 Begin connecting to the NBD server over Unix domain socket ("unix‐
1846 socket"). Parameters behave as documented in nbd_connect_unix(3).
1847 You can check if the connection is still connecting by calling
1849 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1850 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1851 tion.
1852 val aio_connect_vsock : t -> int64 -> int64 -> unit
1856 connect to the NBD server over AF_VSOCK socket
1858 Begin connecting to the NBD server over the "AF_VSOCK" protocol to the
1860 server "cid:port". Parameters behave as documented in nbd_con‐
1861 nect_vsock(3).
1862 You can check if the connection is still connecting by calling
1864 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1865 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1866 tion.
1867 val aio_connect_tcp : t -> string -> string -> unit
1871 connect to the NBD server over a TCP port
1873 Begin connecting to the NBD server listening on "hostname:port". Param‐
1875 eters behave as documented in nbd_connect_tcp(3).
1876 You can check if the connection is still connecting by calling
1878 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1879 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1880 tion.
1881 val aio_connect_socket : t -> Unix.file_descr -> unit
1885 connect directly to a connected socket
1887 Begin connecting to the connected socket "fd". Parameters behave as
1889 documented in nbd_connect_socket(3).
1890 You can check if the connection is still connecting by calling
1892 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1893 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1894 tion.
1895 val aio_connect_command : t -> string list -> unit
1899 connect to the NBD server
1901 Run the command as a subprocess and begin connecting to it over
1903 stdin/stdout. Parameters behave as documented in nbd_connect_com‐
1904 mand(3).
1905 You can check if the connection is still connecting by calling
1907 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1908 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1909 tion.
1910 val aio_connect_systemd_socket_activation : t -> string list -> unit
1914 connect using systemd socket activation
1916 Run the command as a subprocess and begin connecting to it using sys‐
1918 temd socket activation. Parameters behave as documented in nbd_con‐
1919 nect_systemd_socket_activation(3).
1920 You can check if the connection is still connecting by calling
1922 nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1923 pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1924 tion.
1925 val aio_opt_go : ?completion:(int Stdlib.ref -> int) -> t -> unit
1929 end negotiation and move on to using an export
1931 Request that the server finish negotiation and move on to serving the
1933 export previously specified by the most recent nbd_set_export_name(3)
1934 or nbd_connect_uri(3). This can only be used if nbd_set_opt_mode(3)
1935 enabled option mode.
1936 To determine when the request completes, wait for nbd_aio_is_connect‐
1938 ing(3) to return false. Or supply the optional "completion_callback"
1939 which will be invoked as described in "Completion callbacks" in
1940 libnbd(3), except that it is automatically retired regardless of return
1941 value. Note that directly detecting whether the server returns an error
1942 (as is done by the return value of the synchronous counterpart) is only
1943 possible with a completion callback; however it is also possible to in‐
1944 directly detect an error when nbd_aio_is_negotiating(3) returns true.
1945 val aio_opt_abort : t -> unit
1949 end negotiation and close the connection
1951 Request that the server finish negotiation, gracefully if possible,
1953 then close the connection. This can only be used if nbd_set_opt_mode(3)
1954 enabled option mode.
1955 To determine when the request completes, wait for nbd_aio_is_connect‐
1957 ing(3) to return false.
1958 val aio_opt_list : ?completion:(int Stdlib.ref -> int) -> t -> (string
1962 -> string -> int) -> unit
1963 request the server to list all exports during negotiation
1965 Request that the server list all exports that it supports. This can
1967 only be used if nbd_set_opt_mode(3) enabled option mode.
1968 To determine when the request completes, wait for nbd_aio_is_connect‐
1970 ing(3) to return false. Or supply the optional "completion_callback"
1971 which will be invoked as described in "Completion callbacks" in
1972 libnbd(3), except that it is automatically retired regardless of return
1973 value. Note that detecting whether the server returns an error (as is
1974 done by the return value of the synchronous counterpart) is only possi‐
1975 ble with a completion callback.
1976 val aio_opt_info : ?completion:(int Stdlib.ref -> int) -> t -> unit
1980 request the server for information about an export
1982 Request that the server supply information about the export name previ‐
1984 ously specified by the most recent nbd_set_export_name(3) or nbd_con‐
1985 nect_uri(3). This can only be used if nbd_set_opt_mode(3) enabled op‐
1986 tion mode.
1987 To determine when the request completes, wait for nbd_aio_is_connect‐
1989 ing(3) to return false. Or supply the optional "completion_callback"
1990 which will be invoked as described in "Completion callbacks" in
1991 libnbd(3), except that it is automatically retired regardless of return
1992 value. Note that detecting whether the server returns an error (as is
1993 done by the return value of the synchronous counterpart) is only possi‐
1994 ble with a completion callback.
1995 val aio_opt_list_meta_context : ?completion:(int Stdlib.ref -> int) ->
1999 t -> (string -> int) -> int
2000 request the server to list available meta contexts
2002 Request that the server list available meta contexts associated with
2004 the export previously specified by the most recent nbd_set_ex‐
2005 port_name(3) or nbd_connect_uri(3). This can only be used if
2006 nbd_set_opt_mode(3) enabled option mode.
2007 To determine when the request completes, wait for nbd_aio_is_connect‐
2009 ing(3) to return false. Or supply the optional "completion_callback"
2010 which will be invoked as described in "Completion callbacks" in
2011 libnbd(3), except that it is automatically retired regardless of return
2012 value. Note that detecting whether the server returns an error (as is
2013 done by the return value of the synchronous counterpart) is only possi‐
2014 ble with a completion callback.
2015 val aio_pread : ?completion:(int Stdlib.ref -> int) ->
2019 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> cookie
2020 read from the NBD server
2022 Issue a read command to the NBD server.
2024 To check if the command completed, call nbd_aio_command_completed(3).
2026 Or supply the optional "completion_callback" which will be invoked as
2027 described in "Completion callbacks" in libnbd(3).
2028 Note that you must ensure "buf" is valid until the command has com‐
2030 pleted. Furthermore, if the "error" parameter to "completion_callback"
2031 is set or if nbd_aio_command_completed(3) reports failure, and if
2032 nbd_get_pread_initialize(3) returns true, then libnbd sanitized "buf",
2033 but it is unspecified whether the contents of "buf" will read as zero
2034 or as partial results from the server. If nbd_get_pread_initialize(3)
2035 returns false, then libnbd did not sanitize "buf", and the contents are
2036 undefined on failure.
2037 Other parameters behave as documented in nbd_pread(3).
2039 By default, libnbd will reject attempts to use this function with pa‐
2041 rameters that are likely to result in server failure, such as request‐
2042 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2043 used to alter which scenarios should await a server reply rather than
2044 failing fast.
2045 val aio_pread_structured : ?completion:(int Stdlib.ref -> int) ->
2049 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> (bytes -> int64 ->
2050 int -> int Stdlib.ref -> int) -> cookie
2051 read from the NBD server
2053 Issue a read command to the NBD server.
2055 To check if the command completed, call nbd_aio_command_completed(3).
2057 Or supply the optional "completion_callback" which will be invoked as
2058 described in "Completion callbacks" in libnbd(3).
2059 Note that you must ensure "buf" is valid until the command has com‐
2061 pleted. Furthermore, if the "error" parameter to "completion_callback"
2062 is set or if nbd_aio_command_completed(3) reports failure, and if
2063 nbd_get_pread_initialize(3) returns true, then libnbd sanitized "buf",
2064 but it is unspecified whether the contents of "buf" will read as zero
2065 or as partial results from the server. If nbd_get_pread_initialize(3)
2066 returns false, then libnbd did not sanitize "buf", and the contents are
2067 undefined on failure.
2068 Other parameters behave as documented in nbd_pread_structured(3).
2070 By default, libnbd will reject attempts to use this function with pa‐
2072 rameters that are likely to result in server failure, such as request‐
2073 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2074 used to alter which scenarios should await a server reply rather than
2075 failing fast.
2076 val aio_pwrite : ?completion:(int Stdlib.ref -> int) ->
2080 ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> cookie
2081 write to the NBD server
2083 Issue a write command to the NBD server.
2085 To check if the command completed, call nbd_aio_command_completed(3).
2087 Or supply the optional "completion_callback" which will be invoked as
2088 described in "Completion callbacks" in libnbd(3).
2089 Note that you must ensure "buf" is valid until the command has com‐
2091 pleted. Other parameters behave as documented in nbd_pwrite(3).
2092 By default, libnbd will reject attempts to use this function with pa‐
2094 rameters that are likely to result in server failure, such as request‐
2095 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2096 used to alter which scenarios should await a server reply rather than
2097 failing fast.
2098 val aio_disconnect : ?flags:CMD_FLAG.t list -> t -> unit
2102 disconnect from the NBD server
2104 Issue the disconnect command to the NBD server. This is not a normal
2106 command because NBD servers are not obliged to send a reply. Instead
2107 you should wait for nbd_aio_is_closed(3) to become true on the connec‐
2108 tion. Once this command is issued, you cannot issue any further com‐
2109 mands.
2110 Although libnbd does not prevent you from issuing this command while
2112 still waiting on the replies to previous commands, the NBD protocol
2113 recommends that you wait until there are no other commands in flight
2114 (see nbd_aio_in_flight(3)), to give the server a better chance at a
2115 clean shutdown.
2116 The "flags" parameter must be 0 for now (it exists for future NBD pro‐
2118 tocol extensions). There is no direct synchronous counterpart; however,
2119 nbd_shutdown(3) will call this function if appropriate.
2120 val aio_flush : ?completion:(int Stdlib.ref -> int) ->
2124 ?flags:CMD_FLAG.t list -> t -> cookie
2125 send flush command to the NBD server
2127 Issue the flush command to the NBD server.
2129 To check if the command completed, call nbd_aio_command_completed(3).
2131 Or supply the optional "completion_callback" which will be invoked as
2132 described in "Completion callbacks" in libnbd(3).
2133 Other parameters behave as documented in nbd_flush(3).
2135 By default, libnbd will reject attempts to use this function with pa‐
2137 rameters that are likely to result in server failure, such as request‐
2138 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2139 used to alter which scenarios should await a server reply rather than
2140 failing fast.
2141 val aio_trim : ?completion:(int Stdlib.ref -> int) -> ?flags:CMD_FLAG.t
2145 list -> t -> int64 -> int64 -> cookie
2146 send trim command to the NBD server
2148 Issue a trim command to the NBD server.
2150 To check if the command completed, call nbd_aio_command_completed(3).
2152 Or supply the optional "completion_callback" which will be invoked as
2153 described in "Completion callbacks" in libnbd(3).
2154 Other parameters behave as documented in nbd_trim(3).
2156 By default, libnbd will reject attempts to use this function with pa‐
2158 rameters that are likely to result in server failure, such as request‐
2159 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2160 used to alter which scenarios should await a server reply rather than
2161 failing fast.
2162 val aio_cache : ?completion:(int Stdlib.ref -> int) ->
2166 ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> cookie
2167 send cache (prefetch) command to the NBD server
2169 Issue the cache (prefetch) command to the NBD server.
2171 To check if the command completed, call nbd_aio_command_completed(3).
2173 Or supply the optional "completion_callback" which will be invoked as
2174 described in "Completion callbacks" in libnbd(3).
2175 Other parameters behave as documented in nbd_cache(3).
2177 By default, libnbd will reject attempts to use this function with pa‐
2179 rameters that are likely to result in server failure, such as request‐
2180 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2181 used to alter which scenarios should await a server reply rather than
2182 failing fast.
2183 val aio_zero : ?completion:(int Stdlib.ref -> int) -> ?flags:CMD_FLAG.t
2187 list -> t -> int64 -> int64 -> cookie
2188 send write zeroes command to the NBD server
2190 Issue a write zeroes command to the NBD server.
2192 To check if the command completed, call nbd_aio_command_completed(3).
2194 Or supply the optional "completion_callback" which will be invoked as
2195 described in "Completion callbacks" in libnbd(3).
2196 Other parameters behave as documented in nbd_zero(3).
2198 By default, libnbd will reject attempts to use this function with pa‐
2200 rameters that are likely to result in server failure, such as request‐
2201 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2202 used to alter which scenarios should await a server reply rather than
2203 failing fast.
2204 val aio_block_status : ?completion:(int Stdlib.ref -> int) ->
2208 ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> (string -> int64 ->
2209 int64 array -> int Stdlib.ref -> int) -> cookie
2210 send block status command to the NBD server
2212 Send the block status command to the NBD server.
2214 To check if the command completed, call nbd_aio_command_completed(3).
2216 Or supply the optional "completion_callback" which will be invoked as
2217 described in "Completion callbacks" in libnbd(3).
2218 Other parameters behave as documented in nbd_block_status(3).
2220 By default, libnbd will reject attempts to use this function with pa‐
2222 rameters that are likely to result in server failure, such as request‐
2223 ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2224 used to alter which scenarios should await a server reply rather than
2225 failing fast.
2226 val aio_get_fd : t -> Unix.file_descr
2230 return file descriptor associated with this connection
2232 Return the underlying file descriptor associated with this connection.
2234 You can use this to check if the file descriptor is ready for reading
2235 or writing and call nbd_aio_notify_read(3) or nbd_aio_notify_write(3).
2236 See also nbd_aio_get_direction(3). Do not do anything else with the
2237 file descriptor.
2238 val aio_get_direction : t -> int
2242 return the read or write direction
2244 Return the current direction of this connection, which means whether we
2246 are next expecting to read data from the server, write data to the
2247 server, or both. It returns
2248 0 We are not expected to interact with the server file descriptor
2250 from the current state. It is not worth attempting to use poll(2); if
2251 the connection is not dead, then state machine progress must instead
2252 come from some other means such as nbd_aio_connect(3).
2253 "LIBNBD_AIO_DIRECTION_READ" = 1 We are expected next to read from the
2255 server. If using poll(2) you would set "events = POLLIN". If "revents"
2256 returns "POLLIN" or "POLLHUP" you would then call nbd_aio_no‐
2257 tify_read(3).
2258 Note that once libnbd reaches nbd_aio_is_ready(3), this direction is
2260 returned even when there are no commands in flight (see
2261 nbd_aio_in_flight(3)). In a single-threaded use of libnbd, it is not
2262 worth polling until after issuing a command, as otherwise the server
2263 will never wake up the poll. In a multi-threaded scenario, you can have
2264 one thread begin a polling loop prior to any commands, but any other
2265 thread that issues a command will need a way to kick the polling thread
2266 out of poll in case issuing the command changes the needed polling di‐
2267 rection. Possible ways to do this include polling for activity on a
2268 pipe-to-self, or using pthread_kill(3) to send a signal that is masked
2269 except during ppoll(2).
2270 "LIBNBD_AIO_DIRECTION_WRITE" = 2 We are expected next to write to the
2272 server. If using poll(2) you would set "events = POLLOUT". If "revents"
2273 returns "POLLOUT" you would then call nbd_aio_notify_write(3).
2274 "LIBNBD_AIO_DIRECTION_BOTH" = 3 We are expected next to either read or
2276 write to the server. If using poll(2) you would set "events =
2277 POLLIN|POLLOUT". If only one of "POLLIN" or "POLLOUT" is returned, then
2278 see above. However, if both are returned, it is better to call only
2279 nbd_aio_notify_read(3), as processing the server's reply may change the
2280 state of the connection and invalidate the need to write more commands.
2281 val aio_notify_read : t -> unit
2285 notify that the connection is readable
2287 Send notification to the state machine that the connection is readable.
2289 Typically this is called after your main loop has detected that the
2290 file descriptor associated with this connection is readable.
2291 val aio_notify_write : t -> unit
2295 notify that the connection is writable
2297 Send notification to the state machine that the connection is writable.
2299 Typically this is called after your main loop has detected that the
2300 file descriptor associated with this connection is writable.
2301 val aio_is_created : t -> bool
2305 check if the connection has just been created
2307 Return true if this connection has just been created. This is the
2309 state before the handle has started connecting to a server. In this
2310 state the handle can start to be connected by calling functions such as
2311 nbd_aio_connect(3).
2312 val aio_is_connecting : t -> bool
2316 check if the connection is connecting or handshaking
2318 Return true if this connection is connecting to the server or in the
2320 process of handshaking and negotiating options which happens before the
2321 handle becomes ready to issue commands (see nbd_aio_is_ready(3)).
2322 val aio_is_negotiating : t -> bool
2326 check if connection is ready to send handshake option
2328 Return true if this connection is ready to start another option negoti‐
2330 ation command while handshaking with the server. An option command will
2331 move back to the connecting state (see nbd_aio_is_connecting(3)). Note
2332 that this state cannot be reached unless requested by
2333 nbd_set_opt_mode(3), and even then it only works with newstyle servers;
2334 an oldstyle server will skip straight to nbd_aio_is_ready(3).
2335 val aio_is_ready : t -> bool
2339 check if the connection is in the ready state
2341 Return true if this connection is connected to the NBD server, the
2343 handshake has completed, and the connection is idle or waiting for a
2344 reply. In this state the handle is ready to issue commands.
2345 val aio_is_processing : t -> bool
2349 check if the connection is processing a command
2351 Return true if this connection is connected to the NBD server, the
2353 handshake has completed, and the connection is processing commands (ei‐
2354 ther writing out a request or reading a reply).
2355 Note the ready state (nbd_aio_is_ready(3)) is not included. In the
2357 ready state commands may be *in flight* (the *server* is processing
2358 them), but libnbd is not processing them.
2359 val aio_is_dead : t -> bool
2363 check if the connection is dead
2365 Return true if the connection has encountered a fatal error and is
2367 dead. In this state the handle may only be closed. There is no way to
2368 recover a handle from the dead state.
2369 val aio_is_closed : t -> bool
2373 check if the connection is closed
2375 Return true if the connection has closed. There is no way to reconnect
2377 a closed connection. Instead you must close the whole handle.
2378 val aio_command_completed : t -> int64 -> bool
2382 check if the command completed
2384 Return true if the command completed. If this function returns true
2386 then the command was successful and it has been retired. Return false
2387 if the command is still in flight. This can also fail with an error in
2388 case the command failed (in this case the command is also retired). A
2389 command is retired either via this command, or by using a completion
2390 callback which returns 1.
2391 The "cookie" parameter is the positive unique 64 bit cookie for the
2393 command, as returned by a call such as nbd_aio_pread(3).
2394 val aio_peek_command_completed : t -> int64
2398 check if any command has completed
2400 Return the unique positive 64 bit cookie of the first non-retired but
2402 completed command, 0 if there are in-flight commands but none of them
2403 are awaiting retirement, or -1 on error including when there are no
2404 in-flight commands. Any cookie returned by this function must still be
2405 passed to nbd_aio_command_completed(3) to actually retire the command
2406 and learn whether the command was successful.
2407 val aio_in_flight : t -> int
2411 check how many aio commands are still in flight
2413 Return the number of in-flight aio commands that are still awaiting a
2415 response from the server before they can be retired. If this returns a
2416 non-zero value when requesting a disconnect from the server (see
2417 nbd_aio_disconnect(3) and nbd_shutdown(3)), libnbd does not try to wait
2418 for those commands to complete gracefully; if the server strands com‐
2419 mands while shutting down, nbd_aio_command_completed(3) will report
2420 those commands as failed with a status of "ENOTCONN".
2421 val connection_state : t -> string
2425 return string describing the state of the connection
2427 Returns a descriptive string for the state of the connection. This can
2429 be used for debugging or troubleshooting, but you should not rely on
2430 the state of connections since it may change in future versions.
2431 val get_package_name : t -> string
2435 return the name of the library
2437 Returns the name of the library, always "libnbd" unless the library was
2439 modified with another name at compile time.
2440 val get_version : t -> string
2444 return the version of the library
2446 Return the version of libnbd. This is returned as a string in the form
2448 "major.minor.release" where each of major, minor and release is a small
2449 positive integer. For example:
2450 minor ↓ "1.0.3" ↑ ↑ major release
2452 major = 0 The major number was 0 for the early experimental versions of
2454 libnbd where we still had an unstable API.
2455 major = 1 The major number is 1 for the versions of libnbd with a
2457 long-term stable API and ABI. It is not anticipated that major will be
2458 any number other than 1.
2459 minor = 0, 2, ... (even) The minor number is even for stable releases.
2461 minor = 1, 3, ... (odd) The minor number is odd for development ver‐
2463 sions. Note that new APIs added in a development version remain exper‐
2464 imental and subject to change in that branch until they appear in a
2465 stable release.
2466 release The release number is incremented for each release along a par‐
2468 ticular branch.
2469 val kill_subprocess : t -> int -> unit
2473 kill server running as a subprocess
2475 This call may be used to kill the server running as a subprocess that
2477 was previously created using nbd_connect_command(3). You do not need to
2478 use this call. It is only needed if the server does not exit when the
2479 socket is closed.
2480 The "signum" parameter is the optional signal number to send (see sig‐
2482 nal(7)). If "signum" is 0 then "SIGTERM" is sent.
2483 val supports_tls : t -> bool
2487 true if libnbd was compiled with support for TLS
2489 Returns true if libnbd was compiled with gnutls which is required to
2491 support TLS encryption, or false if not.
2492 val supports_uri : t -> bool
2496 true if libnbd was compiled with support for NBD URIs
2498 Returns true if libnbd was compiled with libxml2 which is required to
2500 support NBD URIs, or false if not.
2501 val get_uri : t -> string
2505 construct an NBD URI for a connection
2507 This makes a best effort attempt to construct an NBD URI which could be
2509 used to connect back to the same server (using nbd_connect_uri(3)).
2510 In some cases there is not enough information in the handle to success‐
2512 fully create a URI (eg. if you connected with nbd_connect_socket(3)).
2513 In such cases the call returns "NULL" and further diagnostic informa‐
2514 tion is available via nbd_get_errno(3) and nbd_get_error(3) as usual.
2515 Even if a URI is returned it is not guaranteed to work, and it may not
2517 be optimal.
2518OCamldoc 2022-07-10 NBD(3)