1NBD(3)                                                                  NBD(3)
2
3
4

NAME

6       NBD - OCaml bindings for libnbd.
7

Module

9       Module   NBD
10

Documentation

12       Module NBD
13        : sig end
14
15
16       OCaml bindings for libnbd.
17
18       For full documentation see libnbd-ocaml(3) and libnbd(3).
19
20       For examples written in OCaml see the libnbd source code ocaml/examples
21       subdirectory.
22
23
24
25
26
27
28       exception Error of string * int
29
30
31       Exception thrown when an API call fails.
32
33       The string is the error message, and the  int  is  the  raw  errno  (if
34       available).
35
36
37
38       exception Closed of string
39
40
41       Exception thrown if you call a closed handle.
42
43
44       type cookie = int64
45
46
47
48
49       module TLS : sig end
50
51
52
53
54       module SIZE : sig end
55
56
57
58
59       module CMD_FLAG : sig end
60
61
62
63
64       module HANDSHAKE_FLAG : sig end
65
66
67
68
69       module STRICT : sig end
70
71
72
73
74       module ALLOW_TRANSPORT : sig end
75
76
77
78
79       module SHUTDOWN : sig end
80
81
82
83
84
85       val aio_direction_read : int32
86
87
88
89
90       val aio_direction_write : int32
91
92
93
94
95       val aio_direction_both : int32
96
97
98
99
100       val read_data : int32
101
102
103
104
105       val read_hole : int32
106
107
108
109
110       val read_error : int32
111
112
113
114
115       val namespace_base : string
116
117
118
119
120       val context_base_allocation : string
121
122
123
124
125       val state_hole : int32
126
127
128
129
130       val state_zero : int32
131
132
133
134       module Buffer : sig end
135
136
137       Persistent buffer used in AIO calls.
138
139
140       type t
141
142
143       The handle.
144
145
146
147       val create : unit -> t
148
149       Create a new handle.
150
151
152
153       val close : t -> unit
154
155       Close a handle.
156
157       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
161
162
163       val set_debug : t -> bool -> unit
164
165       set or clear the debug flag
166
167       Set  or clear the debug flag. When debugging is enabled, debugging mes‐
168       sages from the library are printed to stderr, unless a debugging  call‐
169       back has been defined too (see nbd_set_debug_callback(3)) in which case
170       they are sent to that function. This flag defaults to  false  on  newly
171       created  handles,  except if "LIBNBD_DEBUG=1" is set in the environment
172       in which case it defaults to true.
173
174
175
176       val get_debug : t -> bool
177
178       return the state of the debug flag
179
180       Return the state of the debug flag on this handle.
181
182
183
184       val set_debug_callback : t -> (string -> string -> int) -> unit
185
186       set the debug callback
187
188       Set the debug callback. This function is called when the library  emits
189       debug messages, when debugging is enabled on a handle. The callback pa‐
190       rameters are "user_data" passed to  this  function,  the  name  of  the
191       libnbd function emitting the debug message ("context"), and the message
192       itself ("msg"). If no debug callback is set on a handle  then  messages
193       are printed on "stderr".
194
195       The  callback  should not call "nbd_*" APIs on the same handle since it
196       can be called while holding the handle lock and will cause a deadlock.
197
198
199
200       val clear_debug_callback : t -> unit
201
202       clear the debug callback
203
204       Remove the debug callback if one was  previously  associated  with  the
205       handle  (with nbd_set_debug_callback(3)). If no callback was associated
206       this does nothing.
207
208
209
210       val set_handle_name : t -> string -> unit
211
212       set the handle name
213
214       Handles have a name which is unique within  the  current  process.  The
215       handle name is used in debug output.
216
217       Handle  names  are  normally  generated automatically and have the form
218       "nbd1", "nbd2", etc., but you can optionally use this call to give  the
219       handles  a name which is meaningful for your application to make debug‐
220       ging output easier to understand.
221
222
223
224       val get_handle_name : t -> string
225
226       get the handle name
227
228       Get the name of the  handle.  If  it  was  previously  set  by  calling
229       nbd_set_handle_name(3)  then this returns the name that was set. Other‐
230       wise it will return a generic name like "nbd1", "nbd2", etc.
231
232
233
234       val set_private_data : t -> int -> int
235
236       set the per-handle private data
237
238       Handles contain a private data field for applications to  use  for  any
239       purpose.
240
241       When calling libnbd from C, the type of this field is "uintptr_t" so it
242       can be used to store an unsigned integer or a pointer.
243
244       In non-C bindings it can be used to store an unsigned integer.
245
246       This function sets the value of this field and returns  the  old  value
247       (or 0 if it was not previously set).
248
249
250
251       val get_private_data : t -> int
252
253       get the per-handle private data
254
255       Return  the value of the private data field set previously by a call to
256       nbd_set_private_data(3) (or 0 if it was not previously set).
257
258
259
260       val set_export_name : t -> string -> unit
261
262       set the export name
263
264       For servers which require an export name or can serve different content
265       on  different exports, set the "export_name" to connect to. The default
266       is the empty string "".
267
268       This is only relevant when connecting to  servers  using  the  newstyle
269       protocol as the oldstyle protocol did not support export names. The NBD
270       protocol limits export names to 4096 bytes, but servers may not support
271       the full length. The encoding of export names is always UTF-8.
272
273       When  option mode is not in use, the export name must be set before be‐
274       ginning a connection. However, when nbd_set_opt_mode(3) has enabled op‐
275       tion  mode,  it  is  possible  to  change  the  export  name  prior  to
276       nbd_opt_go(3). In particular, the use of nbd_opt_list(3) during negoti‐
277       ation  can  be used to determine a name the server is likely to accept,
278       and nbd_opt_info(3) can be used to learn details about an export before
279       connecting.
280
281       This  call  may  be skipped if using nbd_connect_uri(3) to connect to a
282       URI that includes an export name.
283
284
285
286       val get_export_name : t -> string
287
288       get the export name
289
290       Get the export name associated with the handle. This is the  name  that
291       libnbd  requests;  see nbd_get_canonical_export_name(3) for determining
292       if the server has a different canonical name for the given export (most
293       common when requesting the default export name of an empty string "")
294
295
296
297       val set_full_info : t -> bool -> unit
298
299       control whether NBD_OPT_GO requests extra details
300
301       By  default, when connecting to an export, libnbd only requests the de‐
302       tails it needs to service data operations. The NBD protocol says that a
303       server can supply optional information, such as a canonical name of the
304       export (see nbd_get_canonical_export_name(3)) or a description  of  the
305       export  (see  nbd_get_export_description(3)),  but that a hint from the
306       client makes it more likely for this extra information to be  provided.
307       This function controls whether libnbd will provide that hint.
308
309       Note that even when full info is requested, the server is not obligated
310       to reply with all information that libnbd requested. Similarly,  libnbd
311       will  ignore  any  optional  server information that libnbd has not yet
312       been taught to recognize.
313
314
315
316       val get_full_info : t -> bool
317
318       see if NBD_OPT_GO requests extra details
319
320       Return the state of the full info request flag on this handle.
321
322
323
324       val get_canonical_export_name : t -> string
325
326       return the canonical export name, if the server has one
327
328       The NBD protocol permits a server to report an optional  canonical  ex‐
329       port  name,  which  may  differ  from  the  client's request (as set by
330       nbd_set_export_name(3) or nbd_connect_uri(3)). This  function  accesses
331       any  name  returned by the server; it may be the same as the client re‐
332       quest, but is more likely to differ when the client requested a connec‐
333       tion to the default export name (an empty string "").
334
335       Some  servers are unlikely to report a canonical name unless the client
336       specifically hinted about wanting it, via nbd_set_full_info(3).
337
338
339
340       val get_export_description : t -> string
341
342       return the export description, if the server has one
343
344       The NBD protocol permits a server to report an optional export descrip‐
345       tion. This function reports any description returned by the server.
346
347       Some  servers  are  unlikely  to report a description unless the client
348       specifically hinted about wanting  it,  via  nbd_set_full_info(3).  For
349       qemu-nbd(8), a description is set with *-D*.
350
351
352
353       val set_tls : t -> TLS.t -> unit
354
355       enable or require TLS (authentication and encryption)
356
357       Enable  or require TLS (authenticated and encrypted connections) to the
358       NBD server. The possible settings are:
359
360       "LIBNBD_TLS_DISABLE" Disable TLS. (The default  setting,  unless  using
361       nbd_connect_uri(3) with a URI that requires TLS)
362
363       "LIBNBD_TLS_ALLOW" Enable TLS if possible.
364
365       This  option is insecure (or best effort) in that in some cases it will
366       fall back to an unencrypted and/or unauthenticated  connection  if  TLS
367       could not be established. Use "LIBNBD_TLS_REQUIRE" below if the connec‐
368       tion must be encrypted.
369
370       Some servers will drop the connection if TLS fails so fallback may  not
371       be possible.
372
373       "LIBNBD_TLS_REQUIRE" Require an encrypted and authenticated TLS connec‐
374       tion. Always fail to connect if the connection is not encrypted and au‐
375       thenticated.
376
377       As  well  as  calling  this you may also need to supply the path to the
378       certificates  directory  (nbd_set_tls_certificates(3)),  the   username
379       (nbd_set_tls_username(3))   and/or   the  Pre-Shared  Keys  (PSK)  file
380       (nbd_set_tls_psk_file(3)). For now, when using nbd_connect_uri(3),  any
381       URI query parameters related to TLS are not handled automatically. Set‐
382       ting the level higher than zero will fail if libnbd  was  not  compiled
383       against  gnutls;  you  can  test whether this is the case with nbd_sup‐
384       ports_tls(3).
385
386
387
388       val get_tls : t -> TLS.t
389
390       get the TLS request setting
391
392       Get the TLS request setting.
393
394       Note: If you want to find out if TLS was actually negotiated on a  par‐
395       ticular connection use nbd_get_tls_negotiated(3) instead.
396
397
398
399       val get_tls_negotiated : t -> bool
400
401       find out if TLS was negotiated on a connection
402
403       After connecting you may call this to find out if the connection is us‐
404       ing TLS.
405
406       This is only  really  useful  if  you  set  the  TLS  request  mode  to
407       "LIBNBD_TLS_ALLOW" (see nbd_set_tls(3)), because in this mode we try to
408       use TLS but fall back to unencrypted if  it  was  not  available.  This
409       function will tell you if TLS was negotiated or not.
410
411       In  "LIBNBD_TLS_REQUIRE"  mode  (the  most secure) the connection would
412       have failed if TLS could not be negotiated, and in "LIBNBD_TLS_DISABLE"
413       mode TLS is not tried.
414
415
416
417       val set_tls_certificates : t -> string -> unit
418
419       set the path to the TLS certificates directory
420
421       Set  the  path to the TLS certificates directory. If not set and TLS is
422       used  then  a  compiled  in  default  is  used.   For  root   this   is
423       "/etc/pki/libnbd/".   For  non-root  this  is  "$HOME/.pki/libnbd"  and
424       "$HOME/.config/pki/libnbd".  If none of these directories can be  found
425       then the system trusted CAs are used.
426
427       This function may be called regardless of whether TLS is supported, but
428       will have no effect unless nbd_set_tls(3) is also used  to  request  or
429       require TLS.
430
431
432
433       val set_tls_verify_peer : t -> bool -> unit
434
435       set whether we verify the identity of the server
436
437       Set this flag to control whether libnbd will verify the identity of the
438       server from the server's certificate  and  the  certificate  authority.
439       This defaults to true when connecting to TCP servers using TLS certifi‐
440       cate authentication, and false otherwise.
441
442       This function may be called regardless of whether TLS is supported, but
443       will  have  no  effect unless nbd_set_tls(3) is also used to request or
444       require TLS.
445
446
447
448       val get_tls_verify_peer : t -> bool
449
450       get whether we verify the identity of the server
451
452       Get the verify peer flag.
453
454
455
456       val set_tls_username : t -> string -> unit
457
458       set the TLS username
459
460       Set the TLS client username. This is used if  authenticating  with  PSK
461       over TLS is enabled. If not set then the local username is used.
462
463       This function may be called regardless of whether TLS is supported, but
464       will have no effect unless nbd_set_tls(3) is also used  to  request  or
465       require TLS.
466
467
468
469       val get_tls_username : t -> string
470
471       get the current TLS username
472
473       Get the current TLS username.
474
475
476
477       val set_tls_psk_file : t -> string -> unit
478
479       set the TLS Pre-Shared Keys (PSK) filename
480
481       Set  the  TLS Pre-Shared Keys (PSK) filename. This is used if trying to
482       authenticate to the server using with a pre-shared key. There is no de‐
483       fault  so  if this is not set then PSK authentication cannot be used to
484       connect to the server.
485
486       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
490
491
492       val set_request_structured_replies : t -> bool -> unit
493
494       control use of structured replies
495
496       By default, libnbd tries  to  negotiate  structured  replies  with  the
497       server,   as   this   protocol   extension   must   be  in  use  before
498       nbd_can_meta_context(3) or nbd_can_df(3) can return true. However,  for
499       integration  testing,  it  can be useful to clear this flag rather than
500       find a way to alter the server to fail the negotiation request.
501
502
503
504       val get_request_structured_replies : t -> bool
505
506       see if structured replies are attempted
507
508       Return the state of the request structured replies flag on this handle.
509
510       Note: If you want to find out if structured replies were actually nego‐
511       tiated  on a particular connection use nbd_get_structured_replies_nego‐
512       tiated(3) instead.
513
514
515
516       val get_structured_replies_negotiated : t -> bool
517
518       see if structured replies are in use
519
520       After connecting you may call this to find out if the connection is us‐
521       ing structured replies.
522
523
524
525       val set_handshake_flags : t -> HANDSHAKE_FLAG.t list -> unit
526
527       control use of handshake flags
528
529       By default, libnbd tries to negotiate all possible handshake flags that
530       are also supported by the server, since omitting a handshake  flag  can
531       prevent the use of other functionality such as TLS encryption or struc‐
532       tured replies. However, for integration testing, it can  be  useful  to
533       reduce the set of flags supported by the client to test that a particu‐
534       lar server can handle various clients that were compliant to older ver‐
535       sions of the NBD specification.
536
537       The  "flags"  argument is a bitmask, including zero or more of the fol‐
538       lowing handshake flags:
539
540       "LIBNBD_HANDSHAKE_FLAG_FIXED_NEWSTYLE" = 1 The server  gracefully  han‐
541       dles  unknown  option requests from the client, rather than disconnect‐
542       ing.  Without this flag, a client cannot safely request to  use  exten‐
543       sions  such as TLS encryption or structured replies, as the request may
544       cause an older server to drop the connection.
545
546       "LIBNBD_HANDSHAKE_FLAG_NO_ZEROES" = 2 If the client is  forced  to  use
547       "NBD_OPT_EXPORT_NAME"  instead of the preferred "NBD_OPT_GO", this flag
548       allows the server to send fewer all-zero padding bytes over the connec‐
549       tion.
550
551       For convenience, the constant "LIBNBD_HANDSHAKE_FLAG_MASK" is available
552       to describe all flags supported by this build of libnbd. Future NBD ex‐
553       tensions may add further flags, which in turn may be enabled by default
554       in newer libnbd. As such, when attempting to disable only one  specific
555       bit,  it  is  wiser to first call nbd_get_handshake_flags(3) and modify
556       that value, rather than blindly setting a constant value.
557
558
559
560       val get_handshake_flags : t -> HANDSHAKE_FLAG.t list
561
562       see which handshake flags are supported
563
564       Return the state of the handshake flags on this handle.  When the  han‐
565       dle  has  not  yet  completed a connection (see nbd_aio_is_created(3)),
566       this returns the flags that the client is willing to use, provided  the
567       server  also advertises those flags. After the connection is ready (see
568       nbd_aio_is_ready(3)), this returns the flags that were actually  agreed
569       on  between  the  server  and  client.  If the NBD protocol defines new
570       handshake flags, then the return value from a newer library version may
571       include bits that were undefined at the time of compilation.
572
573
574
575       val set_strict_mode : t -> STRICT.t list -> unit
576
577       control how strictly to follow NBD protocol
578
579       By  default,  libnbd  tries to detect requests that would trigger unde‐
580       fined behavior in the NBD protocol, and rejects them client side  with‐
581       out  causing  any network traffic, rather than risking undefined server
582       behavior.  However, for integration testing, it can be handy  to  relax
583       the  strictness of libnbd, to coerce it into sending such requests over
584       the network for testing the robustness of the server  in  dealing  with
585       such traffic.
586
587       The  "flags"  argument is a bitmask, including zero or more of the fol‐
588       lowing strictness flags:
589
590       "LIBNBD_STRICT_COMMANDS" = 1 If set, this flag rejects client  requests
591       that  do  not comply with the set of advertised server flags (for exam‐
592       ple, attempting a write on a read-only server,  or  attempting  to  use
593       "LIBNBD_CMD_FLAG_FUA"  when  nbd_can_fua(3)  returned false). If clear,
594       this flag relies on the server to reject unexpected commands.
595
596       "LIBNBD_STRICT_FLAGS" = 2 If set, this  flag  rejects  client  requests
597       that attempt to set a command flag not recognized by libnbd (those out‐
598       side of "LIBNBD_CMD_FLAG_MASK"), or a flag not normally associated with
599       a  command (such as using "LIBNBD_CMD_FLAG_FUA" on a read command).  If
600       clear, all flags are sent on to the server, even if sending such a flag
601       may  cause  the  server  to  change its reply in a manner that confuses
602       libnbd, perhaps causing deadlock or ending the connection.
603
604       Flags that are known by libnbd as associated with a given command (such
605       as    "LIBNBD_CMD_FLAG_DF"   for   nbd_pread_structured(3)   gated   by
606       nbd_can_df(3)) are controlled by "LIBNBD_STRICT_COMMANDS" instead.
607
608       Note that the NBD protocol only supports 16 bits of command flags, even
609       though  the  libnbd API uses "uint32_t"; bits outside of the range per‐
610       mitted by the protocol are always a client-side error.
611
612       "LIBNBD_STRICT_BOUNDS" = 3 If set, this flag  rejects  client  requests
613       that  would exceed the export bounds without sending any traffic to the
614       server.  If  clear,  this  flag  relies  on  the   server   to   detect
615       out-of-bounds requests.
616
617       "LIBNBD_STRICT_ZERO_SIZE" = 4 If set, this flag rejects client requests
618       with length 0. If clear,  this  permits  zero-length  requests  to  the
619       server, which may produce undefined results.
620
621       "LIBNBD_STRICT_ALIGN" = 5 If set, and the server provided minimum block
622       sizes (see nbd_get_block_size(3), this  flag  rejects  client  requests
623       that  do not have length and offset aligned to the server's minimum re‐
624       quirements. If clear, unaligned requests are sent to the server,  where
625       it is up to the server whether to honor or reject the request.
626
627       For  convenience, the constant "LIBNBD_STRICT_MASK" is available to de‐
628       scribe all strictness flags supported by this build of  libnbd.  Future
629       versions  of  libnbd  may add further flags, which are likely to be en‐
630       abled by default for additional client-side filtering.  As  such,  when
631       attempting  to  relax  only  one  specific  bit while keeping remaining
632       checks  at   the   client   side,   it   is   wiser   to   first   call
633       nbd_get_strict_mode(3)  and modify that value, rather than blindly set‐
634       ting a constant value.
635
636
637
638       val get_strict_mode : t -> STRICT.t list
639
640       see which strictness flags are in effect
641
642       Return flags indicating which protocol strictness items are  being  en‐
643       forced  locally by libnbd rather than the server. The return value from
644       a newer library version may include bits that  were  undefined  at  the
645       time of compilation.
646
647
648
649       val set_opt_mode : t -> bool -> unit
650
651       control option mode, for pausing during option negotiation
652
653       Set  this  flag  to  true in order to request that a connection command
654       "nbd_connect_*" will pause for negotiation options rather than proceed‐
655       ing  all the way to the ready state, when communicating with a newstyle
656       server. This setting has no  effect  when  connecting  to  an  oldstyle
657       server.
658
659       When  option  mode is enabled, you have fine-grained control over which
660       options are negotiated, compared to the default of the server negotiat‐
661       ing  everything  on your behalf using settings made before starting the
662       connection. To leave the mode and proceed on to the  ready  state,  you
663       must  use nbd_opt_go(3) successfully; a failed nbd_opt_go(3) returns to
664       the negotiating state to allow a change of export  name  before  trying
665       again.  You may also use nbd_opt_abort(3) to end the connection without
666       finishing negotiation.
667
668
669
670       val get_opt_mode : t -> bool
671
672       return whether option mode was enabled
673
674       Return true if option negotiation mode was enabled on this handle.
675
676
677
678       val opt_go : t -> unit
679
680       end negotiation and move on to using an export
681
682       Request that the server finish negotiation and move on to  serving  the
683       export  previously  specified by the most recent nbd_set_export_name(3)
684       or nbd_connect_uri(3).  This can only be  used  if  nbd_set_opt_mode(3)
685       enabled option mode.
686
687       If this fails, the server may still be in negotiation, where it is pos‐
688       sible to attempt another option such as a different  export  name;  al‐
689       though older servers will instead have killed the connection.
690
691
692
693       val opt_abort : t -> unit
694
695       end negotiation and close the connection
696
697       Request  that  the  server  finish negotiation, gracefully if possible,
698       then close the connection. This can only be used if nbd_set_opt_mode(3)
699       enabled option mode.
700
701
702
703       val opt_list : t -> (string -> string -> int) -> int
704
705       request the server to list all exports during negotiation
706
707       Request  that  the  server  list all exports that it supports. This can
708       only be used if nbd_set_opt_mode(3) enabled option mode.
709
710       The "list" function is called once  per  advertised  export,  with  any
711       "user_data"  passed to this function, and with "name" and "description"
712       supplied by the server. Many servers omit descriptions, in  which  case
713       "description"  will be an empty string. Remember that it is not safe to
714       call nbd_set_export_name(3) from within the  context  of  the  callback
715       function;  rather,  your code must copy any "name" needed for later use
716       after this function completes. At present,  the  return  value  of  the
717       callback is ignored, although a return of -1 should be avoided.
718
719       For  convenience, when this function succeeds, it returns the number of
720       exports that were advertised by the server.
721
722       Not all servers understand this request, and even  when  it  is  under‐
723       stood, the server might intentionally send an empty list to avoid being
724       an information leak, may encounter a failure after  delivering  partial
725       results,  or may refuse to answer more than one query per connection in
726       the interest of avoiding negotiation that does not resolve. Thus,  this
727       function may succeed even when no exports are reported, or may fail but
728       have a non-empty list. Likewise, the NBD protocol does not  specify  an
729       upper  bound  for  the  number  of exports that might be advertised, so
730       client code should be aware that a server may send a lengthy list.
731
732       For nbd-server(1) you will need to allow clients to make list  requests
733       by   adding   "allowlist=true"   to   the   "   generic  "  section  of
734       /etc/nbd-server/config. For qemu-nbd(8),  a  description  is  set  with
735       *-D*.
736
737
738
739       val opt_info : t -> unit
740
741       request the server for information about an export
742
743       Request that the server supply information about the export name previ‐
744       ously specified by the most recent nbd_set_export_name(3)  or  nbd_con‐
745       nect_uri(3).  This  can only be used if nbd_set_opt_mode(3) enabled op‐
746       tion mode.
747
748       If successful, functions like nbd_is_read_only(3)  and  nbd_get_size(3)
749       will report details about that export.  In general, if nbd_opt_go(3) is
750       called next, that call will likely succeed with the  details  remaining
751       the same, although this is not guaranteed by all servers.
752
753       Not  all  servers  understand  this request, and even when it is under‐
754       stood, the server might fail the  request  even  when  a  corresponding
755       nbd_opt_go(3) would succeed.
756
757
758
759       val opt_list_meta_context : t -> (string -> int) -> int
760
761       request the server to list available meta contexts
762
763       Request  that  the  server list available meta contexts associated with
764       the  export  previously  specified  by  the  most  recent   nbd_set_ex‐
765       port_name(3)   or   nbd_connect_uri(3).   This  can  only  be  used  if
766       nbd_set_opt_mode(3) enabled option mode.
767
768       The NBD protocol allows a client to decide how many queries to ask  the
769       server.  Rather than taking that list of queries as a parameter to this
770       function, libnbd reuses the current list of requested meta contexts  as
771       set  by nbd_add_meta_context(3); you can use nbd_clear_meta_contexts(3)
772       to set up a different list of queries. When the list is empty, a server
773       will  typically reply with all contexts that it supports; when the list
774       is non-empty, the server will reply only with supported  contexts  that
775       match  the  client's  request. Note that a reply by the server might be
776       encoded to represent  several  feasible  contexts  within  one  string,
777       rather  than  multiple strings per actual context name that would actu‐
778       ally succeed during nbd_opt_go(3); so it  is  still  necessary  to  use
779       nbd_can_meta_context(3)  after connecting to see which contexts are ac‐
780       tually supported.
781
782       The "context" function is  called  once  per  server  reply,  with  any
783       "user_data"  passed  to  this function, and with "name" supplied by the
784       server. Remember that it is not safe  to  call  nbd_add_meta_context(3)
785       from  within  the  context  of the callback function; rather, your code
786       must copy any "name" needed for later  use  after  this  function  com‐
787       pletes.  At  present,  the return value of the callback is ignored, al‐
788       though a return of -1 should be avoided.
789
790       For convenience, when this function succeeds, it returns the number  of
791       replies returned by the server.
792
793       Not  all  servers  understand  this request, and even when it is under‐
794       stood, the server might intentionally send an  empty  list  because  it
795       does  not support the requested context, or may encounter a failure af‐
796       ter delivering partial results. Thus, this function  may  succeed  even
797       when  no  contexts are reported, or may fail but have a non-empty list.
798       Likewise, the NBD protocol does not specify an upper bound for the num‐
799       ber of replies that might be advertised, so client code should be aware
800       that a server may send a lengthy list.
801
802
803
804       val add_meta_context : t -> string -> unit
805
806       ask server to negotiate metadata context
807
808       During connection libnbd can negotiate zero or more  metadata  contexts
809       with  the server. Metadata contexts are features (such as "base:alloca‐
810       tion") which describe information returned by  the  nbd_block_status(3)
811       command (for "base:allocation" this is whether blocks of data are allo‐
812       cated, zero or sparse).
813
814       This call adds one metadata context to the list to be  negotiated.  You
815       can  call  it as many times as needed. The list is initially empty when
816       the handle is created; you can check the  contents  of  the  list  with
817       nbd_get_nr_meta_contexts(3)  and  nbd_get_meta_context(3),  or clear it
818       with nbd_clear_meta_contexts(3).
819
820       The NBD protocol limits meta context names to 4096 bytes,  but  servers
821       may  not support the full length. The encoding of meta context names is
822       always UTF-8.
823
824       Not all servers support all metadata contexts. To learn  if  a  context
825       was actually negotiated, call nbd_can_meta_context(3) after connecting.
826
827       The  single  parameter is the name of the metadata context, for example
828       "LIBNBD_CONTEXT_BASE_ALLOCATION".   <libnbd.h>  includes  defined  con‐
829       stants  beginning  with "LIBNBD_CONTEXT_" for some well-known contexts,
830       but you are free to pass in other contexts.
831
832       Other   metadata   contexts   are    server-specific,    but    include
833       "qemu:dirty-bitmap:..."  and  "qemu:allocation-depth" for qemu-nbd (see
834       qemu-nbd *-B* and *-A* options).
835
836
837
838       val get_nr_meta_contexts : t -> int
839
840       return the current number of requested meta contexts
841
842       During connection libnbd can negotiate zero or more  metadata  contexts
843       with  the server. Metadata contexts are features (such as "base:alloca‐
844       tion") which describe information returned by  the  nbd_block_status(3)
845       command (for "base:allocation" this is whether blocks of data are allo‐
846       cated, zero or sparse).
847
848       This command returns how many meta contexts have been added to the list
849       to  request  from the server via nbd_add_meta_context(3). The server is
850       not obligated to honor all of the requests; to  see  what  it  actually
851       supports, see nbd_can_meta_context(3).
852
853
854
855       val get_meta_context : t -> int -> string
856
857       return the i'th meta context request
858
859       During  connection  libnbd can negotiate zero or more metadata contexts
860       with the server. Metadata contexts are features (such as  "base:alloca‐
861       tion")  which  describe information returned by the nbd_block_status(3)
862       command (for "base:allocation" this is whether blocks of data are allo‐
863       cated, zero or sparse).
864
865       This  command  returns  the  i'th  meta  context  request,  as added by
866       nbd_add_meta_context(3), and bounded by nbd_get_nr_meta_contexts(3).
867
868
869
870       val clear_meta_contexts : t -> unit
871
872       reset the list of requested meta contexts
873
874       During connection libnbd can negotiate zero or more  metadata  contexts
875       with  the server. Metadata contexts are features (such as "base:alloca‐
876       tion") which describe information returned by  the  nbd_block_status(3)
877       command (for "base:allocation" this is whether blocks of data are allo‐
878       cated, zero or sparse).
879
880       This command resets the list of meta contexts to  request  back  to  an
881       empty  list,  for  re-population  by  further  use of nbd_add_meta_con‐
882       text(3). It is primarily useful when option  negotiation  mode  is  se‐
883       lected  (see  nbd_set_opt_mode(3)),  for altering the list of attempted
884       contexts between subsequent export queries.
885
886
887
888       val set_uri_allow_transports : t -> ALLOW_TRANSPORT.t list -> unit
889
890       set the allowed transports in NBD URIs
891
892       Set which transports are allowed to appear in NBD URIs.  The default is
893       to allow any transport.
894
895       The  "mask"  parameter  may contain any of the following flags ORed to‐
896       gether:
897
898       "LIBNBD_ALLOW_TRANSPORT_TCP" "LIBNBD_ALLOW_TRANSPORT_UNIX"  "LIBNBD_AL‐
899       LOW_TRANSPORT_VSOCK"
900
901       For  convenience,  the constant "LIBNBD_ALLOW_TRANSPORT_MASK" is avail‐
902       able to describe all transports recognized by this build of  libnbd.  A
903       future version of the library may add new flags.
904
905
906
907       val set_uri_allow_tls : t -> TLS.t -> unit
908
909       set the allowed TLS settings in NBD URIs
910
911       Set  which  TLS settings are allowed to appear in NBD URIs. The default
912       is to allow either non-TLS or TLS URIs.
913
914       The "tls" parameter can be:
915
916       "LIBNBD_TLS_DISABLE" TLS URIs are not permitted,  ie.  a  URI  such  as
917       "nbds://..." will be rejected.
918
919       "LIBNBD_TLS_ALLOW" This is the default. TLS may be used or not, depend‐
920       ing on whether the URI uses "nbds" or "nbd".
921
922       "LIBNBD_TLS_REQUIRE" TLS URIs are required. All URIs must use "nbds".
923
924
925
926       val set_uri_allow_local_file : t -> bool -> unit
927
928       set the allowed transports in NBD URIs
929
930       Allow NBD URIs to reference local files. This is *disabled* by default.
931
932       Currently this setting only controls whether the "tls-psk-file" parame‐
933       ter in NBD URIs is allowed.
934
935
936
937       val connect_uri : t -> string -> unit
938
939       connect to NBD URI
940
941       Connect  (synchronously)  to an NBD server and export by specifying the
942       NBD URI. This call parses the URI and calls nbd_set_export_name(3)  and
943       nbd_set_tls(3)   and  other  calls  as  needed,  followed  by  nbd_con‐
944       nect_tcp(3) or nbd_connect_unix(3).
945
946       This call returns when the connection has been made.
947
948       Example URIs supported  "nbd://example.com"  Connect  over  TCP,  unen‐
949       crypted, to "example.com" port 10809.
950
951       "nbds://example.com"  Connect  over TCP with TLS, to "example.com" port
952       10809. If the server does not support TLS then this will fail.
953
954       "nbd+unix:///foo?socket=/tmp/nbd.sock" Connect  over  the  Unix  domain
955       socket  /tmp/nbd.sock to an NBD server running locally. The export name
956       is set to "foo" (note without any leading "/" character).
957
958       "nbds+unix://alice@/?socket=/tmp/nbd.sock&tls-certificat es=certs" Con‐
959       nect  over a Unix domain socket, enabling TLS and setting the path to a
960       directory containing certificates and keys.
961
962       "nbd+vsock:///" In this scenario libnbd is running  in  a  virtual  ma‐
963       chine. Connect over "AF_VSOCK" to an NBD server running on the hypervi‐
964       sor.
965
966       Supported URI formats The following schemes are supported in  the  cur‐
967       rent version of libnbd:
968
969       "nbd:" Connect over TCP without using TLS.
970
971       "nbds:"  Connect over TCP. TLS is required and the connection will fail
972       if the server does not support TLS.
973
974       "nbd+unix:" "nbds+unix:" Connect over a Unix domain socket, without  or
975       with TLS respectively. The "socket" parameter is required.
976
977       "nbd+vsock:" "nbds+vsock:" Connect over the "AF_VSOCK" transport, with‐
978       out or with TLS respectively.
979
980       The authority part of the URI  ("  username@  servername  :port  ")  is
981       parsed  depending  on the transport. For TCP it specifies the server to
982       connect to and optional port number.  For  "+unix"  it  should  not  be
983       present. For "+vsock" the server name is the numeric CID (eg. 2 to con‐
984       nect to the host), and the optional port number may be present. If  the
985       "username" is present it is used for TLS authentication.
986
987       For all transports, an export name may be present, parsed in accordance
988       with the NBD URI specification.
989
990       Finally the query part of the URI can contain:
991
992       socket=SOCKET Specifies the Unix domain socket to connect on.  Must  be
993       present for the "+unix" transport and must not be present for the other
994       transports.
995
996       tls-certificates=DIR    Set    the    certificates    directory.    See
997       nbd_set_tls_certificates(3).  Note this is not allowed by default - see
998       next section.
999
1000       tls-psk-file=PSKFILE Set the  PSK  file.  See  nbd_set_tls_psk_file(3).
1001       Note this is not allowed by default - see next section.
1002
1003       Disable  URI  features  For  security reasons you might want to disable
1004       certain URI features. Pre-filtering URIs is error-prone and should  not
1005       be attempted. Instead use the libnbd APIs below to control what can ap‐
1006       pear in URIs. Note you must call these functions on the same handle be‐
1007       fore calling nbd_connect_uri(3) or nbd_aio_connect_uri(3).
1008
1009       TCP, Unix domain socket or "AF_VSOCK" transports Default: all allowed
1010
1011       To  select  which  transports are allowed call nbd_set_uri_allow_trans‐
1012       ports(3).
1013
1014       TLS Default: both non-TLS and TLS connections allowed
1015
1016       To force TLS off or on in URIs call nbd_set_uri_allow_tls(3).
1017
1018       Connect to Unix domain socket in the local filesystem Default: allowed
1019
1020       To  prevent  this  you  must  disable  the  "+unix"   transport   using
1021       nbd_set_uri_allow_transports(3).
1022
1023       Read from local files Default: denied
1024
1025       To  allow URIs to contain references to local files (eg. for parameters
1026       like "tls-psk-file") call nbd_set_uri_allow_local_file(3).
1027
1028       Overriding the export name It is possible to override the  export  name
1029       portion  of  a  URI by using nbd_set_opt_mode(3) to enable option mode,
1030       then using nbd_set_export_name(3) and nbd_opt_go(3) as part  of  subse‐
1031       quent negotiation.
1032
1033       Optional  features  This call will fail if libnbd was not compiled with
1034       libxml2;  you  can  test  whether  this  is  the  case  with   nbd_sup‐
1035       ports_uri(3).
1036
1037       Support  for URIs that require TLS will fail if libnbd was not compiled
1038       with gnutls; you can test  whether  this  is  the  case  with  nbd_sup‐
1039       ports_tls(3).
1040
1041       Constructing a URI from an existing connection See nbd_get_uri(3).
1042
1043
1044
1045       val connect_unix : t -> string -> unit
1046
1047       connect to NBD server over a Unix domain socket
1048
1049       Connect  (synchronously)  over  the  named  Unix  domain socket ("unix‐
1050       socket") to an NBD server running on the same machine.  This  call  re‐
1051       turns when the connection has been made.
1052
1053
1054
1055       val connect_vsock : t -> int32 -> int32 -> unit
1056
1057       connect to NBD server over AF_VSOCK protocol
1058
1059       Connect (synchronously) over the "AF_VSOCK" protocol from a virtual ma‐
1060       chine to an NBD server, usually running on  the  host.  The  "cid"  and
1061       "port" parameters specify the server address. Usually "cid" should be 2
1062       (to connect to the host), and "port" might be  10809  or  another  port
1063       number  assigned  to  you  by the host administrator. This call returns
1064       when the connection has been made.
1065
1066
1067
1068       val connect_tcp : t -> string -> string -> unit
1069
1070       connect to NBD server over a TCP port
1071
1072       Connect (synchronously) to the NBD server listening on "hostname:port".
1073       The "port" may be a port name such as "nbd", or it may be a port number
1074       as a string such as "10809". This call returns when the connection  has
1075       been made.
1076
1077
1078
1079       val connect_socket : t -> Unix.file_descr -> unit
1080
1081       connect directly to a connected socket
1082
1083       Pass  a  connected  socket "sock" through which libnbd will talk to the
1084       NBD server.
1085
1086       The caller is responsible for creating and connecting  this  socket  by
1087       some method, before passing it to libnbd.
1088
1089       If  this  call returns without error then socket ownership is passed to
1090       libnbd. Libnbd will close the socket when the  handle  is  closed.  The
1091       caller must not use the socket in any way.
1092
1093
1094
1095       val connect_command : t -> string list -> unit
1096
1097       connect to NBD server command
1098
1099       Run  the  command  as a subprocess and connect to it over stdin/stdout.
1100       This is for use with NBD servers which can behave like  inetd  clients,
1101       such  as  nbdkit(1)  using  the *-s*/*--single* flag, and nbd-server(1)
1102       with port number set to 0.
1103
1104       To run qemu-nbd(1),  use  nbd_connect_systemd_socket_activation(3)  in‐
1105       stead.
1106
1107       Subprocess  Libnbd will fork the "argv" command and pass the NBD socket
1108       to it using file descriptors 0 and 1 (stdin/stdout):
1109
1110       ┌─────────┬─────────┐    ┌────────────────┐ │ program │ libnbd  │     │
1111       NBD  server   │ │         │         │    │       (argv)   │ │         │
1112       socket     ╍╍╍╍╍╍╍╍▶     stdin/stdout      │      └─────────┴─────────┘
1113       └────────────────┘
1114
1115       When the NBD handle is closed the server subprocess is killed.
1116
1117
1118
1119       val connect_systemd_socket_activation : t -> string list -> unit
1120
1121       connect using systemd socket activation
1122
1123       Run  the command as a subprocess and connect to it using systemd socket
1124       activation.
1125
1126       This is especially useful for running qemu-nbd(1) as  a  subprocess  of
1127       libnbd, for example to use it to open qcow2 files.
1128
1129       To  run  nbdkit as a subprocess, this function can be used, or nbd_con‐
1130       nect_command(3).
1131
1132       To run nbd-server(1) as a subprocess, this function cannot be used, you
1133       must use nbd_connect_command(3).
1134
1135       Socket  activation  Libnbd will fork the "argv" command and pass an NBD
1136       socket to it using special "LISTEN_*" environment variables (as defined
1137       by the systemd socket activation protocol).
1138
1139       ┌─────────┬─────────┐     ┌───────────────┐  │ program │ libnbd  │    │
1140       qemu-nbd or  │ │         │         │    │  other server │  │          │
1141       socket        ╍╍╍╍╍╍╍╍▶                   │       └─────────┴─────────┘
1142       └───────────────┘
1143
1144       When the NBD handle is closed the server subprocess is killed.
1145
1146
1147
1148       val is_read_only : t -> bool
1149
1150       is the NBD export read-only?
1151
1152       Returns true if the NBD export is read-only; writes and write-like  op‐
1153       erations will fail.
1154
1155       This  call does not block, because it returns data that is saved in the
1156       handle from the NBD protocol handshake.
1157
1158
1159
1160       val can_flush : t -> bool
1161
1162       does the server support the flush command?
1163
1164       Returns  true  if  the  server  supports   the   flush   command   (see
1165       nbd_flush(3), nbd_aio_flush(3)). Returns false if the server does not.
1166
1167       This  call does not block, because it returns data that is saved in the
1168       handle from the NBD protocol handshake.
1169
1170
1171
1172       val can_fua : t -> bool
1173
1174       does the server support the FUA flag?
1175
1176       Returns true if the server supports the FUA flag  on  certain  commands
1177       (see nbd_pwrite(3)).
1178
1179       This  call does not block, because it returns data that is saved in the
1180       handle from the NBD protocol handshake.
1181
1182
1183
1184       val is_rotational : t -> bool
1185
1186       is the NBD disk rotational (like a disk)?
1187
1188       Returns true if the disk exposed over NBD is rotational (like a  tradi‐
1189       tional  floppy  or hard disk). Returns false if the disk has no penalty
1190       for random access (like an SSD or RAM disk).
1191
1192       This call does not block, because it returns data that is saved in  the
1193       handle from the NBD protocol handshake.
1194
1195
1196
1197       val can_trim : t -> bool
1198
1199       does the server support the trim command?
1200
1201       Returns  true if the server supports the trim command (see nbd_trim(3),
1202       nbd_aio_trim(3)). Returns false if the server does not.
1203
1204       This call does not block, because it returns data that is saved in  the
1205       handle from the NBD protocol handshake.
1206
1207
1208
1209       val can_zero : t -> bool
1210
1211       does the server support the zero command?
1212
1213       Returns  true if the server supports the zero command (see nbd_zero(3),
1214       nbd_aio_zero(3)). Returns false if the server does not.
1215
1216       This call does not block, because it returns data that is saved in  the
1217       handle from the NBD protocol handshake.
1218
1219
1220
1221       val can_fast_zero : t -> bool
1222
1223       does the server support the fast zero flag?
1224
1225       Returns    true    if    the   server   supports   the   use   of   the
1226       "LIBNBD_CMD_FLAG_FAST_ZERO" flag to the zero command (see  nbd_zero(3),
1227       nbd_aio_zero(3)). Returns false if the server does not.
1228
1229       This  call does not block, because it returns data that is saved in the
1230       handle from the NBD protocol handshake.
1231
1232
1233
1234       val can_df : t -> bool
1235
1236       does the server support the don't fragment flag to pread?
1237
1238       Returns true if the server supports structured reads with an ability to
1239       request    a    non-fragmented   read   (see   nbd_pread_structured(3),
1240       nbd_aio_pread_structured(3)).  Returns false if the server either lacks
1241       structured  reads  or  if it does not support a non-fragmented read re‐
1242       quest.
1243
1244       This call does not block, because it returns data that is saved in  the
1245       handle from the NBD protocol handshake.
1246
1247
1248
1249       val can_multi_conn : t -> bool
1250
1251       does the server support multi-conn?
1252
1253       Returns  true  if  the server supports multi-conn. Returns false if the
1254       server does not.
1255
1256       It is not safe to open multiple handles connecting to the  same  server
1257       if  you  will  write  to  the  server and the server does not advertise
1258       multi-conn support. The safe way to check for this is to open one  con‐
1259       nection,  check this flag is true, then open further connections as re‐
1260       quired.
1261
1262       This call does not block, because it returns data that is saved in  the
1263       handle from the NBD protocol handshake.
1264
1265
1266
1267       val can_cache : t -> bool
1268
1269       does the server support the cache command?
1270
1271       Returns   true   if   the   server  supports  the  cache  command  (see
1272       nbd_cache(3), nbd_aio_cache(3)). Returns false if the server does not.
1273
1274       This call does not block, because it returns data that is saved in  the
1275       handle from the NBD protocol handshake.
1276
1277
1278
1279       val can_meta_context : t -> string -> bool
1280
1281       does the server support a specific meta context?
1282
1283       Returns  true  if  the  server  supports  the  given  meta context (see
1284       nbd_add_meta_context(3)). Returns false if the server does not.
1285
1286       The single parameter is the name of the metadata context,  for  example
1287       "LIBNBD_CONTEXT_BASE_ALLOCATION".   <libnbd.h>  includes  defined  con‐
1288       stants for well-known namespace contexts  beginning  with  "LIBNBD_CON‐
1289       TEXT_", but you are free to pass in other contexts.
1290
1291       This  call does not block, because it returns data that is saved in the
1292       handle from the NBD protocol handshake.
1293
1294
1295
1296       val get_protocol : t -> string
1297
1298       return the NBD protocol variant
1299
1300       Return the NBD protocol variant in use on the connection. At the moment
1301       this  returns  one  of  the  strings  "oldstyle",  "newstyle"  or "new‐
1302       style-fixed".  Other strings might be returned in the future. Most mod‐
1303       ern NBD servers use "newstyle-fixed".
1304
1305       This  call does not block, because it returns data that is saved in the
1306       handle from the NBD protocol handshake.
1307
1308
1309
1310       val get_size : t -> int64
1311
1312       return the export size
1313
1314       Returns the size in bytes of the NBD export.
1315
1316       This call does not block, because it returns data that is saved in  the
1317       handle from the NBD protocol handshake.
1318
1319
1320
1321       val get_block_size : t -> SIZE.t -> int64
1322
1323       return a specific server block size constraint
1324
1325       Returns a specific size constraint advertised by the server, if any. If
1326       the return  is  zero,  the  server  did  not  advertise  a  constraint.
1327       "size_type" must be one of the following constraints:
1328
1329       "LIBNBD_SIZE_MINIMUM"  =  0  If non-zero, this will be a power of 2 be‐
1330       tween 1 and 64k; any client request that is not aligned  in  length  or
1331       offset  to  this  size  is likely to fail with "EINVAL". The image size
1332       will generally also be a multiple of this value (if not, the final  few
1333       bytes  are  inaccessible while obeying alignment constraints). If zero,
1334       it is safest to assume a minimum  block  size  of  512,  although  many
1335       servers  support  a  minimum  block size of 1. If the server provides a
1336       constraint,  then  libnbd  defaults   to   honoring   that   constraint
1337       client-side     unless     "LIBNBD_STRICT_ALIGN"    is    cleared    in
1338       nbd_set_strict_mode(3).
1339
1340       "LIBNBD_SIZE_PREFERRED" = 1 If non-zero, this is a power  of  2  repre‐
1341       senting  the preferred size for efficient I/O. Smaller requests may in‐
1342       cur overhead such as read-modify-write cycles that will not be  present
1343       when  using  I/O  that  is  a multiple of this value. This value may be
1344       larger than the size of the export. If zero, using 4k  as  a  preferred
1345       block size tends to give decent performance.
1346
1347       "LIBNBD_SIZE_MAXIMUM"  =  2  If  non-zero,  this represents the maximum
1348       length that the server is willing  to  handle  during  nbd_pread(3)  or
1349       nbd_pwrite(3).  Other  functions  like nbd_zero(3) may still be able to
1350       use larger sizes. Note that this function returns what the  server  ad‐
1351       vertised, but libnbd itself imposes a maximum of 64M. If zero, some NBD
1352       servers will abruptly disconnect if a transaction  involves  more  than
1353       32M.
1354
1355       Future NBD extensions may result in additional "size_type" values.
1356
1357       This  call does not block, because it returns data that is saved in the
1358       handle from the NBD protocol handshake.
1359
1360
1361
1362       val pread : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 -> unit
1363
1364       read from the NBD server
1365
1366       Issue a read command to the NBD server for the range starting at  "off‐
1367       set"  and  ending  at  "offset" + "count" - 1. NBD can only read all or
1368       nothing using this call. The call returns when the data has  been  read
1369       fully  into  "buf"  or  there  is  an  error. See also nbd_pread_struc‐
1370       tured(3), if finer visibility is required into the server's replies, or
1371       if you want to use "LIBNBD_CMD_FLAG_DF".
1372
1373       The  "flags" parameter must be 0 for now (it exists for future NBD pro‐
1374       tocol extensions).
1375
1376       By default, libnbd will reject attempts to use this function  with  pa‐
1377       rameters  that are likely to result in server failure, such as request‐
1378       ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1379       used  to  alter which scenarios should await a server reply rather than
1380       failing fast.
1381
1382
1383
1384       val pread_structured : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 ->
1385       (bytes -> int64 -> int -> int Stdlib.ref -> int) -> unit
1386
1387       read from the NBD server
1388
1389       Issue  a read command to the NBD server for the range starting at "off‐
1390       set" and ending at "offset" + "count" - 1. The server's response may be
1391       subdivided  into chunks which may arrive out of order before reassembly
1392       into the original buffer; the "chunk" callback is used for notification
1393       after each chunk arrives, and may perform additional sanity checking on
1394       the server's reply. The callback cannot call "nbd_*" APIs on  the  same
1395       handle since it holds the handle lock and will cause a deadlock. If the
1396       callback returns -1, and no earlier error has been detected,  then  the
1397       overall  read command will fail with any non-zero value stored into the
1398       callback's "error" parameter (with a default of "EPROTO"); but any fur‐
1399       ther chunks will still invoke the callback.
1400
1401       The  "chunk"  function  is called once per chunk of data received, with
1402       the "user_data" passed to this function.  The "subbuf" and "count"  pa‐
1403       rameters  represent  the  subset  of the original buffer which has just
1404       been populated by results from the server (in C, "subbuf" always points
1405       within  the  original "buf"; but this guarantee may not extend to other
1406       language bindings). The "offset" parameter represents the absolute off‐
1407       set  at  which  "subbuf" begins within the image (note that this is not
1408       the relative offset of "subbuf"  within  the  original  buffer  "buf").
1409       Changes to "error" on output are ignored unless the callback fails. The
1410       input meaning of the "error" parameter is controlled  by  the  "status"
1411       parameter, which is one of
1412
1413       "LIBNBD_READ_DATA"  =  1  "subbuf"  was populated with "count" bytes of
1414       data.  On input, "error" contains the errno value of  any  earlier  de‐
1415       tected error, or zero.
1416
1417       "LIBNBD_READ_HOLE" = 2 "subbuf" represents a hole, and contains "count"
1418       NUL bytes. On input, "error" contains the errno value  of  any  earlier
1419       detected error, or zero.
1420
1421       "LIBNBD_READ_ERROR"  =  3 "count" is 0, so "subbuf" is unusable. On in‐
1422       put, "error" contains the errno value reported by the server as  occur‐
1423       ring  while  reading that "offset", regardless if any earlier error has
1424       been detected.
1425
1426       Future NBD extensions may permit other values for "status",  but  those
1427       will  not  be  returned to a client that has not opted in to requesting
1428       such extensions. If the server is non-compliant, it is possible for the
1429       "chunk"  function  to  be  called  more  times  than you expect or with
1430       "count" 0 for "LIBNBD_READ_DATA" or "LIBNBD_READ_HOLE". It is also pos‐
1431       sible  that  the  "chunk" function is not called at all (in particular,
1432       "LIBNBD_READ_ERROR" is used only when an error  is  associated  with  a
1433       particular  offset,  and  not when the server reports a generic error),
1434       but you are guaranteed that the callback was called at  least  once  if
1435       the  overall  read  succeeds.  Libnbd does not validate that the server
1436       obeyed the requirement that a  read  call  must  not  have  overlapping
1437       chunks  and  must not succeed without enough chunks to cover the entire
1438       request.
1439
1440       The  "flags"  parameter  may  be  0  for  no  flags,  or  may   contain
1441       "LIBNBD_CMD_FLAG_DF" meaning that the server should not reply with more
1442       than one fragment (if that is supported - some servers cannot do  this,
1443       see  nbd_can_df(3)).  Libnbd does not validate that the server actually
1444       obeys the flag.
1445
1446       By default, libnbd will reject attempts to use this function  with  pa‐
1447       rameters  that are likely to result in server failure, such as request‐
1448       ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1449       used  to  alter which scenarios should await a server reply rather than
1450       failing fast.
1451
1452
1453
1454       val pwrite : ?flags:CMD_FLAG.t list -> t -> bytes -> int64 -> unit
1455
1456       write to the NBD server
1457
1458       Issue a write command to the NBD server, writing the data in  "buf"  to
1459       the  range  starting  at "offset" and ending at "offset" + "count" - 1.
1460       NBD can only write all or nothing using this  call.  The  call  returns
1461       when  the  command  has been acknowledged by the server, or there is an
1462       error. Note this will generally return an error if  nbd_is_read_only(3)
1463       is true.
1464
1465       The   "flags"  parameter  may  be  0  for  no  flags,  or  may  contain
1466       "LIBNBD_CMD_FLAG_FUA" meaning that the server should not  return  until
1467       the  data has been committed to permanent storage (if that is supported
1468       - some servers cannot do this, see nbd_can_fua(3)).
1469
1470       By default, libnbd will reject attempts to use this function  with  pa‐
1471       rameters  that are likely to result in server failure, such as request‐
1472       ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1473       used  to  alter which scenarios should await a server reply rather than
1474       failing fast.
1475
1476
1477
1478       val shutdown : ?flags:SHUTDOWN.t list -> t -> unit
1479
1480       disconnect from the NBD server
1481
1482       Issue the disconnect command to the NBD server. This is a nice  way  to
1483       tell  the server we are going away, but from the client's point of view
1484       has  no  advantage  over   abruptly   closing   the   connection   (see
1485       nbd_close(3)).
1486
1487       This function works whether or not the handle is ready for transmission
1488       of commands. If more fine-grained control is needed,  see  nbd_aio_dis‐
1489       connect(3).
1490
1491       The  "flags"  argument is a bitmask, including zero or more of the fol‐
1492       lowing shutdown flags:
1493
1494       "LIBNBD_SHUTDOWN_ABANDON_PENDING" = 0x10000 If there  are  any  pending
1495       requests   which   have   not   yet   been  sent  to  the  server  (see
1496       nbd_aio_in_flight(3)), abandon them without sending them to the server,
1497       rather than the usual practice of issuing those commands before inform‐
1498       ing the server of the intent to disconnect.
1499
1500       For convenience, the constant "LIBNBD_SHUTDOWN_MASK"  is  available  to
1501       describe  all  shutdown flags recognized by this build of libnbd. A fu‐
1502       ture version of the library may add new flags.
1503
1504
1505
1506       val flush : ?flags:CMD_FLAG.t list -> t -> unit
1507
1508       send flush command to the NBD server
1509
1510       Issue the flush command to the NBD server. The function  should  return
1511       when  all  write  commands  which have completed have been committed to
1512       permanent storage on the server. Note this will generally return an er‐
1513       ror if nbd_can_flush(3) is false.
1514
1515       The  "flags" parameter must be 0 for now (it exists for future NBD pro‐
1516       tocol extensions).
1517
1518       By default, libnbd will reject attempts to use this function  with  pa‐
1519       rameters  that are likely to result in server failure, such as request‐
1520       ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1521       used  to  alter which scenarios should await a server reply rather than
1522       failing fast.
1523
1524
1525
1526       val trim : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
1527
1528       send trim command to the NBD server
1529
1530       Issue a trim command to the NBD  server,  which  if  supported  by  the
1531       server  causes  a  hole  to be punched in the backing store starting at
1532       "offset" and ending at "offset" + "count" - 1. The  call  returns  when
1533       the  command has been acknowledged by the server, or there is an error.
1534       Note this will generally return an error if nbd_can_trim(3) is false or
1535       nbd_is_read_only(3) is true.
1536
1537       The   "flags"  parameter  may  be  0  for  no  flags,  or  may  contain
1538       "LIBNBD_CMD_FLAG_FUA" meaning that the server should not  return  until
1539       the  data has been committed to permanent storage (if that is supported
1540       - some servers cannot do this, see nbd_can_fua(3)).
1541
1542       By default, libnbd will reject attempts to use this function  with  pa‐
1543       rameters  that are likely to result in server failure, such as request‐
1544       ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1545       used  to  alter which scenarios should await a server reply rather than
1546       failing fast.
1547
1548
1549
1550       val cache : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
1551
1552       send cache (prefetch) command to the NBD server
1553
1554       Issue the cache (prefetch) command to the NBD  server,  which  if  sup‐
1555       ported  by  the server causes data to be prefetched into faster storage
1556       by the server, speeding up a subsequent nbd_pread(3) call.  The  server
1557       can  also silently ignore this command. Note this will generally return
1558       an error if nbd_can_cache(3) is false.
1559
1560       The "flags" parameter must be 0 for now (it exists for future NBD  pro‐
1561       tocol extensions).
1562
1563       By  default,  libnbd will reject attempts to use this function with pa‐
1564       rameters that are likely to result in server failure, such as  request‐
1565       ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1566       used to alter which scenarios should await a server reply  rather  than
1567       failing fast.
1568
1569
1570
1571       val zero : ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> unit
1572
1573       send write zeroes command to the NBD server
1574
1575       Issue  a  write zeroes command to the NBD server, which if supported by
1576       the server causes a zeroes to be written efficiently starting at  "off‐
1577       set" and ending at "offset"
1578
1579       -"count"  -  1. The call returns when the command has been acknowledged
1580       by the server, or there is an error.  Note this will  generally  return
1581       an error if nbd_can_zero(3) is false or nbd_is_read_only(3) is true.
1582
1583       The   "flags"  parameter  may  be  0  for  no  flags,  or  may  contain
1584       "LIBNBD_CMD_FLAG_FUA" meaning that the server should not  return  until
1585       the  data has been committed to permanent storage (if that is supported
1586       -   some    servers    cannot    do    this,    see    nbd_can_fua(3)),
1587       "LIBNBD_CMD_FLAG_NO_HOLE"  meaning that the server should favor writing
1588       actual   allocated   zeroes    over    punching    a    hole,    and/or
1589       "LIBNBD_CMD_FLAG_FAST_ZERO"  meaning  that the server must fail quickly
1590       if writing zeroes is no faster than a normal write  (if  that  is  sup‐
1591       ported - some servers cannot do this, see nbd_can_fast_zero(3)).
1592
1593       By  default,  libnbd will reject attempts to use this function with pa‐
1594       rameters that are likely to result in server failure, such as  request‐
1595       ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1596       used to alter which scenarios should await a server reply  rather  than
1597       failing fast.
1598
1599
1600
1601       val  block_status  :  ?flags:CMD_FLAG.t  list -> t -> int64 -> int64 ->
1602       (string -> int64 -> int32 array -> int Stdlib.ref -> int) -> unit
1603
1604       send block status command to the NBD server
1605
1606       Issue the block status command to the NBD server. If supported  by  the
1607       server, this causes metadata context information about blocks beginning
1608       from the specified offset to be returned. The "count"  parameter  is  a
1609       hint:  the  server may choose to return less status, or the final block
1610       may extend beyond the requested range. If multiple  contexts  are  sup‐
1611       ported, the number of blocks and cumulative length of those blocks need
1612       not be identical between contexts.
1613
1614       Depending on which metadata contexts  were  enabled  before  connecting
1615       (see  nbd_add_meta_context(3))  and  which  are supported by the server
1616       (see nbd_can_meta_context(3)) this call returns information  about  ex‐
1617       tents  by  calling  back  to the "extent" function. The callback cannot
1618       call "nbd_*" APIs on the same handle since it holds the handle lock and
1619       will cause a deadlock. If the callback returns -1, and no earlier error
1620       has been detected, then the overall block status command will fail with
1621       any non-zero value stored into the callback's "error" parameter (with a
1622       default of "EPROTO"); but any further contexts will  still  invoke  the
1623       callback.
1624
1625       The  "extent"  function  is called once per type of metadata available,
1626       with the "user_data" passed to this function. The "metacontext" parame‐
1627       ter  is  a  string such as "base:allocation". The "entries" array is an
1628       array of pairs of integers with the first entry in each pair being  the
1629       length  (in  bytes)  of  the  block  and  the second entry being a sta‐
1630       tus/flags field which is specific to the metadata context. (The  number
1631       of  pairs  passed  to the function is "nr_entries/2".) The NBD protocol
1632       document in the section about  "NBD_REPLY_TYPE_BLOCK_STATUS"  describes
1633       the  meaning  of  this  array; for contexts known to libnbd, <libnbd.h>
1634       contains constants beginning with "LIBNBD_STATE_" that may  help  deci‐
1635       pher  the  values. On entry to the callback, the "error" parameter con‐
1636       tains the errno value of any previously detected error.
1637
1638       It is possible for the extent function to be called more times than you
1639       expect  (if  the  server  is  buggy), so always check the "metacontext"
1640       field to ensure you are receiving the data you expect. It is also  pos‐
1641       sible  that the extent function is not called at all, even for metadata
1642       contexts that you requested. This  indicates  either  that  the  server
1643       doesn't  support the context or for some other reason cannot return the
1644       data.
1645
1646       The  "flags"  parameter  may  be  0  for  no  flags,  or  may   contain
1647       "LIBNBD_CMD_FLAG_REQ_ONE"  meaning  that  the server should return only
1648       one extent per metadata context  where  that  extent  does  not  exceed
1649       "count" bytes; however, libnbd does not validate that the server obeyed
1650       the flag.
1651
1652       By default, libnbd will reject attempts to use this function  with  pa‐
1653       rameters  that are likely to result in server failure, such as request‐
1654       ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1655       used  to  alter which scenarios should await a server reply rather than
1656       failing fast.
1657
1658
1659
1660       val poll : t -> int -> int
1661
1662       poll the handle once
1663
1664       This is a simple implementation of poll(2) which is used internally  by
1665       synchronous  API  calls.  On success, it returns 0 if the "timeout" (in
1666       milliseconds) occurs, or 1 if the poll completed and the state  machine
1667       progressed.  Set  "timeout" to -1 to block indefinitely (but be careful
1668       that eventual action is actually expected - for example, if the connec‐
1669       tion is established but there are no commands in flight, using an infi‐
1670       nite timeout will permanently block).
1671
1672       This function is mainly useful as an example of how you might integrate
1673       libnbd with your own main loop, rather than being intended as something
1674       you would use.
1675
1676
1677
1678       val aio_connect : t -> string -> unit
1679
1680       connect to the NBD server
1681
1682       Begin connecting to the NBD server. The "addr" and "addrlen" parameters
1683       specify the address of the socket to connect to.
1684
1685       You  can  check  if  the  connection  is  still  connecting  by calling
1686       nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1687       pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1688       tion.
1689
1690
1691
1692       val aio_connect_uri : t -> string -> unit
1693
1694       connect to an NBD URI
1695
1696       Begin connecting to the NBD URI "uri". Parameters behave as  documented
1697       in nbd_connect_uri(3).
1698
1699       You  can  check  if  the  connection  is  still  connecting  by calling
1700       nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1701       pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1702       tion.
1703
1704
1705
1706       val aio_connect_unix : t -> string -> unit
1707
1708       connect to the NBD server over a Unix domain socket
1709
1710       Begin connecting to the NBD server  over  Unix  domain  socket  ("unix‐
1711       socket"). Parameters behave as documented in nbd_connect_unix(3).
1712
1713       You  can  check  if  the  connection  is  still  connecting  by calling
1714       nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1715       pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1716       tion.
1717
1718
1719
1720       val aio_connect_vsock : t -> int32 -> int32 -> unit
1721
1722       connect to the NBD server over AF_VSOCK socket
1723
1724       Begin connecting to the NBD server over the "AF_VSOCK" protocol to  the
1725       server   "cid:port".   Parameters  behave  as  documented  in  nbd_con‐
1726       nect_vsock(3).
1727
1728       You can  check  if  the  connection  is  still  connecting  by  calling
1729       nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1730       pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1731       tion.
1732
1733
1734
1735       val aio_connect_tcp : t -> string -> string -> unit
1736
1737       connect to the NBD server over a TCP port
1738
1739       Begin connecting to the NBD server listening on "hostname:port". Param‐
1740       eters behave as documented in nbd_connect_tcp(3).
1741
1742       You can  check  if  the  connection  is  still  connecting  by  calling
1743       nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1744       pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1745       tion.
1746
1747
1748
1749       val aio_connect_socket : t -> Unix.file_descr -> unit
1750
1751       connect directly to a connected socket
1752
1753       Begin  connecting  to  the connected socket "fd".  Parameters behave as
1754       documented in nbd_connect_socket(3).
1755
1756       You can  check  if  the  connection  is  still  connecting  by  calling
1757       nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1758       pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1759       tion.
1760
1761
1762
1763       val aio_connect_command : t -> string list -> unit
1764
1765       connect to the NBD server
1766
1767       Run  the  command  as  a  subprocess  and  begin  connecting to it over
1768       stdin/stdout.  Parameters  behave  as  documented  in  nbd_connect_com‐
1769       mand(3).
1770
1771       You  can  check  if  the  connection  is  still  connecting  by calling
1772       nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1773       pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1774       tion.
1775
1776
1777
1778       val aio_connect_systemd_socket_activation : t -> string list -> unit
1779
1780       connect using systemd socket activation
1781
1782       Run the command as a subprocess and begin connecting to it  using  sys‐
1783       temd  socket  activation.  Parameters  behave as documented in nbd_con‐
1784       nect_systemd_socket_activation(3).
1785
1786       You can  check  if  the  connection  is  still  connecting  by  calling
1787       nbd_aio_is_connecting(3), or if it has connected to the server and com‐
1788       pleted the NBD handshake by calling nbd_aio_is_ready(3), on the connec‐
1789       tion.
1790
1791
1792
1793       val aio_opt_go : ?completion:(int Stdlib.ref -> int) -> t -> unit
1794
1795       end negotiation and move on to using an export
1796
1797       Request  that  the server finish negotiation and move on to serving the
1798       export previously specified by the most  recent  nbd_set_export_name(3)
1799       or  nbd_connect_uri(3).   This  can only be used if nbd_set_opt_mode(3)
1800       enabled option mode.
1801
1802       To determine when the request completes, wait  for  nbd_aio_is_connect‐
1803       ing(3)  to  return  false. Or supply the optional "completion_callback"
1804       which will  be  invoked  as  described  in  "Completion  callbacks"  in
1805       libnbd(3), except that it is automatically retired regardless of return
1806       value. Note that directly detecting whether the server returns an error
1807       (as is done by the return value of the synchronous counterpart) is only
1808       possible with a completion callback; however it is also possible to in‐
1809       directly detect an error when nbd_aio_is_negotiating(3) returns true.
1810
1811
1812
1813       val aio_opt_abort : t -> unit
1814
1815       end negotiation and close the connection
1816
1817       Request  that  the  server  finish negotiation, gracefully if possible,
1818       then close the connection. This can only be used if nbd_set_opt_mode(3)
1819       enabled option mode.
1820
1821       To  determine  when the request completes, wait for nbd_aio_is_connect‐
1822       ing(3) to return false.
1823
1824
1825
1826       val aio_opt_list : ?completion:(int Stdlib.ref -> int) -> t ->  (string
1827       -> string -> int) -> unit
1828
1829       request the server to list all exports during negotiation
1830
1831       Request  that  the  server  list all exports that it supports. This can
1832       only be used if nbd_set_opt_mode(3) enabled option mode.
1833
1834       To determine when the request completes, wait  for  nbd_aio_is_connect‐
1835       ing(3)  to  return  false. Or supply the optional "completion_callback"
1836       which will  be  invoked  as  described  in  "Completion  callbacks"  in
1837       libnbd(3), except that it is automatically retired regardless of return
1838       value. Note that detecting whether the server returns an error  (as  is
1839       done by the return value of the synchronous counterpart) is only possi‐
1840       ble with a completion callback.
1841
1842
1843
1844       val aio_opt_info : ?completion:(int Stdlib.ref -> int) -> t -> unit
1845
1846       request the server for information about an export
1847
1848       Request that the server supply information about the export name previ‐
1849       ously  specified  by the most recent nbd_set_export_name(3) or nbd_con‐
1850       nect_uri(3). This can only be used if nbd_set_opt_mode(3)  enabled  op‐
1851       tion mode.
1852
1853       To  determine  when the request completes, wait for nbd_aio_is_connect‐
1854       ing(3) to return false. Or supply  the  optional  "completion_callback"
1855       which  will  be  invoked  as  described  in  "Completion  callbacks" in
1856       libnbd(3), except that it is automatically retired regardless of return
1857       value.  Note  that detecting whether the server returns an error (as is
1858       done by the return value of the synchronous counterpart) is only possi‐
1859       ble with a completion callback.
1860
1861
1862
1863       val  aio_opt_list_meta_context : ?completion:(int Stdlib.ref -> int) ->
1864       t -> (string -> int) -> int
1865
1866       request the server to list available meta contexts
1867
1868       Request that the server list available meta  contexts  associated  with
1869       the   export  previously  specified  by  the  most  recent  nbd_set_ex‐
1870       port_name(3)  or  nbd_connect_uri(3).  This  can  only   be   used   if
1871       nbd_set_opt_mode(3) enabled option mode.
1872
1873       To  determine  when the request completes, wait for nbd_aio_is_connect‐
1874       ing(3) to return false. Or supply  the  optional  "completion_callback"
1875       which  will  be  invoked  as  described  in  "Completion  callbacks" in
1876       libnbd(3), except that it is automatically retired regardless of return
1877       value.  Note  that detecting whether the server returns an error (as is
1878       done by the return value of the synchronous counterpart) is only possi‐
1879       ble with a completion callback.
1880
1881
1882
1883       val    aio_pread    :    ?completion:(int   Stdlib.ref   ->   int)   ->
1884       ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> cookie
1885
1886       read from the NBD server
1887
1888       Issue a read command to the NBD server.
1889
1890       To check if the command completed,  call  nbd_aio_command_completed(3).
1891       Or  supply  the optional "completion_callback" which will be invoked as
1892       described in "Completion callbacks" in libnbd(3).
1893
1894       Note that you must ensure "buf" is valid until  the  command  has  com‐
1895       pleted. Other parameters behave as documented in nbd_pread(3).
1896
1897       By  default,  libnbd will reject attempts to use this function with pa‐
1898       rameters that are likely to result in server failure, such as  request‐
1899       ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1900       used to alter which scenarios should await a server reply  rather  than
1901       failing fast.
1902
1903
1904
1905       val  aio_pread_structured  :  ?completion:(int  Stdlib.ref  ->  int) ->
1906       ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> (bytes -> int64  ->
1907       int -> int Stdlib.ref -> int) -> cookie
1908
1909       read from the NBD server
1910
1911       Issue a read command to the NBD server.
1912
1913       To  check  if the command completed, call nbd_aio_command_completed(3).
1914       Or supply the optional "completion_callback" which will be  invoked  as
1915       described in "Completion callbacks" in libnbd(3).
1916
1917       Other parameters behave as documented in nbd_pread_structured(3).
1918
1919       By  default,  libnbd will reject attempts to use this function with pa‐
1920       rameters that are likely to result in server failure, such as  request‐
1921       ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1922       used to alter which scenarios should await a server reply  rather  than
1923       failing fast.
1924
1925
1926
1927       val    aio_pwrite    :   ?completion:(int   Stdlib.ref   ->   int)   ->
1928       ?flags:CMD_FLAG.t list -> t -> Buffer.t -> int64 -> cookie
1929
1930       write to the NBD server
1931
1932       Issue a write command to the NBD server.
1933
1934       To check if the command completed,  call  nbd_aio_command_completed(3).
1935       Or  supply  the optional "completion_callback" which will be invoked as
1936       described in "Completion callbacks" in libnbd(3).
1937
1938       Note that you must ensure "buf" is valid until  the  command  has  com‐
1939       pleted. Other parameters behave as documented in nbd_pwrite(3).
1940
1941       By  default,  libnbd will reject attempts to use this function with pa‐
1942       rameters that are likely to result in server failure, such as  request‐
1943       ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1944       used to alter which scenarios should await a server reply  rather  than
1945       failing fast.
1946
1947
1948
1949       val aio_disconnect : ?flags:CMD_FLAG.t list -> t -> unit
1950
1951       disconnect from the NBD server
1952
1953       Issue  the  disconnect  command to the NBD server. This is not a normal
1954       command because NBD servers are not obliged to send  a  reply.  Instead
1955       you  should wait for nbd_aio_is_closed(3) to become true on the connec‐
1956       tion.  Once this command is issued, you cannot issue any  further  com‐
1957       mands.
1958
1959       Although  libnbd  does  not prevent you from issuing this command while
1960       still waiting on the replies to previous  commands,  the  NBD  protocol
1961       recommends  that  you  wait until there are no other commands in flight
1962       (see nbd_aio_in_flight(3)), to give the server a  better  chance  at  a
1963       clean shutdown.
1964
1965       The  "flags" parameter must be 0 for now (it exists for future NBD pro‐
1966       tocol extensions). There is no direct synchronous counterpart; however,
1967       nbd_shutdown(3) will call this function if appropriate.
1968
1969
1970
1971       val    aio_flush    :    ?completion:(int   Stdlib.ref   ->   int)   ->
1972       ?flags:CMD_FLAG.t list -> t -> cookie
1973
1974       send flush command to the NBD server
1975
1976       Issue the flush command to the NBD server.
1977
1978       To check if the command completed,  call  nbd_aio_command_completed(3).
1979       Or  supply  the optional "completion_callback" which will be invoked as
1980       described in "Completion callbacks" in libnbd(3).
1981
1982       Other parameters behave as documented in nbd_flush(3).
1983
1984       By default, libnbd will reject attempts to use this function  with  pa‐
1985       rameters  that are likely to result in server failure, such as request‐
1986       ing an unknown command flag. The nbd_set_strict_mode(3) function can be
1987       used  to  alter which scenarios should await a server reply rather than
1988       failing fast.
1989
1990
1991
1992       val aio_trim : ?completion:(int Stdlib.ref -> int) -> ?flags:CMD_FLAG.t
1993       list -> t -> int64 -> int64 -> cookie
1994
1995       send trim command to the NBD server
1996
1997       Issue a trim command to the NBD server.
1998
1999       To  check  if the command completed, call nbd_aio_command_completed(3).
2000       Or supply the optional "completion_callback" which will be  invoked  as
2001       described in "Completion callbacks" in libnbd(3).
2002
2003       Other parameters behave as documented in nbd_trim(3).
2004
2005       By  default,  libnbd will reject attempts to use this function with pa‐
2006       rameters that are likely to result in server failure, such as  request‐
2007       ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2008       used to alter which scenarios should await a server reply  rather  than
2009       failing fast.
2010
2011
2012
2013       val    aio_cache    :    ?completion:(int   Stdlib.ref   ->   int)   ->
2014       ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> cookie
2015
2016       send cache (prefetch) command to the NBD server
2017
2018       Issue the cache (prefetch) command to the NBD server.
2019
2020       To check if the command completed,  call  nbd_aio_command_completed(3).
2021       Or  supply  the optional "completion_callback" which will be invoked as
2022       described in "Completion callbacks" in libnbd(3).
2023
2024       Other parameters behave as documented in nbd_cache(3).
2025
2026       By default, libnbd will reject attempts to use this function  with  pa‐
2027       rameters  that are likely to result in server failure, such as request‐
2028       ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2029       used  to  alter which scenarios should await a server reply rather than
2030       failing fast.
2031
2032
2033
2034       val aio_zero : ?completion:(int Stdlib.ref -> int) -> ?flags:CMD_FLAG.t
2035       list -> t -> int64 -> int64 -> cookie
2036
2037       send write zeroes command to the NBD server
2038
2039       Issue a write zeroes command to the NBD server.
2040
2041       To  check  if the command completed, call nbd_aio_command_completed(3).
2042       Or supply the optional "completion_callback" which will be  invoked  as
2043       described in "Completion callbacks" in libnbd(3).
2044
2045       Other parameters behave as documented in nbd_zero(3).
2046
2047       By  default,  libnbd will reject attempts to use this function with pa‐
2048       rameters that are likely to result in server failure, such as  request‐
2049       ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2050       used to alter which scenarios should await a server reply  rather  than
2051       failing fast.
2052
2053
2054
2055       val   aio_block_status   :   ?completion:(int  Stdlib.ref  ->  int)  ->
2056       ?flags:CMD_FLAG.t list -> t -> int64 -> int64 -> (string  ->  int64  ->
2057       int32 array -> int Stdlib.ref -> int) -> cookie
2058
2059       send block status command to the NBD server
2060
2061       Send the block status command to the NBD server.
2062
2063       To  check  if the command completed, call nbd_aio_command_completed(3).
2064       Or supply the optional "completion_callback" which will be  invoked  as
2065       described in "Completion callbacks" in libnbd(3).
2066
2067       Other parameters behave as documented in nbd_block_status(3).
2068
2069       By  default,  libnbd will reject attempts to use this function with pa‐
2070       rameters that are likely to result in server failure, such as  request‐
2071       ing an unknown command flag. The nbd_set_strict_mode(3) function can be
2072       used to alter which scenarios should await a server reply  rather  than
2073       failing fast.
2074
2075
2076
2077       val aio_get_fd : t -> Unix.file_descr
2078
2079       return file descriptor associated with this connection
2080
2081       Return  the underlying file descriptor associated with this connection.
2082       You can use this to check if the file descriptor is ready  for  reading
2083       or  writing and call nbd_aio_notify_read(3) or nbd_aio_notify_write(3).
2084       See also nbd_aio_get_direction(3). Do not do  anything  else  with  the
2085       file descriptor.
2086
2087
2088
2089       val aio_get_direction : t -> int
2090
2091       return the read or write direction
2092
2093       Return the current direction of this connection, which means whether we
2094       are next expecting to read data from the  server,  write  data  to  the
2095       server, or both. It returns
2096
2097       0    We  are  not  expected to interact with the server file descriptor
2098       from the current state. It is not worth attempting to use  poll(2);  if
2099       the  connection  is  not dead, then state machine progress must instead
2100       come from some other means such as nbd_aio_connect(3).
2101
2102       "LIBNBD_AIO_DIRECTION_READ" = 1 We are expected next to read  from  the
2103       server.  If using poll(2) you would set "events = POLLIN". If "revents"
2104       returns  "POLLIN"  or  "POLLHUP"  you  would  then   call   nbd_aio_no‐
2105       tify_read(3).
2106
2107       Note  that  once  libnbd reaches nbd_aio_is_ready(3), this direction is
2108       returned  even  when   there   are   no   commands   in   flight   (see
2109       nbd_aio_in_flight(3)).  In  a  single-threaded use of libnbd, it is not
2110       worth polling until after issuing a command, as  otherwise  the  server
2111       will never wake up the poll. In a multi-threaded scenario, you can have
2112       one thread begin a polling loop prior to any commands,  but  any  other
2113       thread that issues a command will need a way to kick the polling thread
2114       out of poll in case issuing the command changes the needed polling  di‐
2115       rection.  Possible  ways  to  do this include polling for activity on a
2116       pipe-to-self, or using pthread_kill(3) to send a signal that is  masked
2117       except during ppoll(2).
2118
2119       "LIBNBD_AIO_DIRECTION_WRITE"  =  2 We are expected next to write to the
2120       server. If using poll(2) you would set "events = POLLOUT". If "revents"
2121       returns "POLLOUT" you would then call nbd_aio_notify_write(3).
2122
2123       "LIBNBD_AIO_DIRECTION_BOTH"  = 3 We are expected next to either read or
2124       write to  the  server.  If  using  poll(2)  you  would  set  "events  =
2125       POLLIN|POLLOUT". If only one of "POLLIN" or "POLLOUT" is returned, then
2126       see above. However, if both are returned, it is  better  to  call  only
2127       nbd_aio_notify_read(3), as processing the server's reply may change the
2128       state of the connection and invalidate the need to write more commands.
2129
2130
2131
2132       val aio_notify_read : t -> unit
2133
2134       notify that the connection is readable
2135
2136       Send notification to the state machine that the connection is readable.
2137       Typically  this  is  called  after your main loop has detected that the
2138       file descriptor associated with this connection is readable.
2139
2140
2141
2142       val aio_notify_write : t -> unit
2143
2144       notify that the connection is writable
2145
2146       Send notification to the state machine that the connection is writable.
2147       Typically  this  is  called  after your main loop has detected that the
2148       file descriptor associated with this connection is writable.
2149
2150
2151
2152       val aio_is_created : t -> bool
2153
2154       check if the connection has just been created
2155
2156       Return true if this connection has just  been  created.   This  is  the
2157       state  before  the  handle  has started connecting to a server. In this
2158       state the handle can start to be connected by calling functions such as
2159       nbd_aio_connect(3).
2160
2161
2162
2163       val aio_is_connecting : t -> bool
2164
2165       check if the connection is connecting or handshaking
2166
2167       Return  true  if  this connection is connecting to the server or in the
2168       process of handshaking and negotiating options which happens before the
2169       handle becomes ready to issue commands (see nbd_aio_is_ready(3)).
2170
2171
2172
2173       val aio_is_negotiating : t -> bool
2174
2175       check if connection is ready to send handshake option
2176
2177       Return true if this connection is ready to start another option negoti‐
2178       ation command while handshaking with the server. An option command will
2179       move  back to the connecting state (see nbd_aio_is_connecting(3)). Note
2180       that   this   state   cannot   be   reached   unless    requested    by
2181       nbd_set_opt_mode(3), and even then it only works with newstyle servers;
2182       an oldstyle server will skip straight to nbd_aio_is_ready(3).
2183
2184
2185
2186       val aio_is_ready : t -> bool
2187
2188       check if the connection is in the ready state
2189
2190       Return true if this connection is connected  to  the  NBD  server,  the
2191       handshake  has  completed,  and the connection is idle or waiting for a
2192       reply. In this state the handle is ready to issue commands.
2193
2194
2195
2196       val aio_is_processing : t -> bool
2197
2198       check if the connection is processing a command
2199
2200       Return true if this connection is connected  to  the  NBD  server,  the
2201       handshake has completed, and the connection is processing commands (ei‐
2202       ther writing out a request or reading a reply).
2203
2204       Note the ready state (nbd_aio_is_ready(3))  is  not  included.  In  the
2205       ready  state  commands  may  be *in flight* (the *server* is processing
2206       them), but libnbd is not processing them.
2207
2208
2209
2210       val aio_is_dead : t -> bool
2211
2212       check if the connection is dead
2213
2214       Return true if the connection has encountered  a  fatal  error  and  is
2215       dead.  In  this state the handle may only be closed. There is no way to
2216       recover a handle from the dead state.
2217
2218
2219
2220       val aio_is_closed : t -> bool
2221
2222       check if the connection is closed
2223
2224       Return true if the connection has closed. There is no way to  reconnect
2225       a closed connection. Instead you must close the whole handle.
2226
2227
2228
2229       val aio_command_completed : t -> int64 -> bool
2230
2231       check if the command completed
2232
2233       Return  true  if  the  command completed. If this function returns true
2234       then the command was successful and it has been retired.  Return  false
2235       if  the command is still in flight. This can also fail with an error in
2236       case the command failed (in this case the command is also  retired).  A
2237       command  is  retired  either via this command, or by using a completion
2238       callback which returns 1.
2239
2240       The "cookie" parameter is the positive unique 64  bit  cookie  for  the
2241       command, as returned by a call such as nbd_aio_pread(3).
2242
2243
2244
2245       val aio_peek_command_completed : t -> int64
2246
2247       check if any command has completed
2248
2249       Return  the  unique positive 64 bit cookie of the first non-retired but
2250       completed command, 0 if there are in-flight commands but none  of  them
2251       are  awaiting  retirement,  or  -1 on error including when there are no
2252       in-flight commands. Any cookie returned by this function must still  be
2253       passed  to  nbd_aio_command_completed(3) to actually retire the command
2254       and learn whether the command was successful.
2255
2256
2257
2258       val aio_in_flight : t -> int
2259
2260       check how many aio commands are still in flight
2261
2262       Return the number of in-flight aio commands that are still  awaiting  a
2263       response  from the server before they can be retired. If this returns a
2264       non-zero value when  requesting  a  disconnect  from  the  server  (see
2265       nbd_aio_disconnect(3) and nbd_shutdown(3)), libnbd does not try to wait
2266       for those commands to complete gracefully; if the server  strands  com‐
2267       mands  while  shutting  down,  nbd_aio_command_completed(3) will report
2268       those commands as failed with a status of "ENOTCONN".
2269
2270
2271
2272       val connection_state : t -> string
2273
2274       return string describing the state of the connection
2275
2276       Returns a descriptive string for the state of the connection. This  can
2277       be  used  for  debugging or troubleshooting, but you should not rely on
2278       the state of connections since it may change in future versions.
2279
2280
2281
2282       val get_package_name : t -> string
2283
2284       return the name of the library
2285
2286       Returns the name of the library, always "libnbd" unless the library was
2287       modified with another name at compile time.
2288
2289
2290
2291       val get_version : t -> string
2292
2293       return the version of the library
2294
2295       Return  the version of libnbd. This is returned as a string in the form
2296       "major.minor.release" where each of major, minor and release is a small
2297       positive integer.  For example:
2298
2299       minor ↓ "1.0.3" ↑   ↑ major   release
2300
2301       major = 0 The major number was 0 for the early experimental versions of
2302       libnbd where we still had an unstable API.
2303
2304       major = 1 The major number is 1 for  the  versions  of  libnbd  with  a
2305       long-term  stable API and ABI. It is not anticipated that major will be
2306       any number other than 1.
2307
2308       minor = 0, 2, ... (even) The minor number is even for stable releases.
2309
2310       minor = 1, 3, ... (odd) The minor number is odd  for  development  ver‐
2311       sions.  Note that new APIs added in a development version remain exper‐
2312       imental and subject to change in that branch until  they  appear  in  a
2313       stable release.
2314
2315       release The release number is incremented for each release along a par‐
2316       ticular branch.
2317
2318
2319
2320       val kill_subprocess : t -> int -> unit
2321
2322       kill server running as a subprocess
2323
2324       This call may be used to kill the server running as a  subprocess  that
2325       was previously created using nbd_connect_command(3). You do not need to
2326       use this call. It is only needed if the server does not exit  when  the
2327       socket is closed.
2328
2329       The  "signum" parameter is the optional signal number to send (see sig‐
2330       nal(7)). If "signum" is 0 then "SIGTERM" is sent.
2331
2332
2333
2334       val supports_tls : t -> bool
2335
2336       true if libnbd was compiled with support for TLS
2337
2338       Returns true if libnbd was compiled with gnutls which  is  required  to
2339       support TLS encryption, or false if not.
2340
2341
2342
2343       val supports_uri : t -> bool
2344
2345       true if libnbd was compiled with support for NBD URIs
2346
2347       Returns  true  if libnbd was compiled with libxml2 which is required to
2348       support NBD URIs, or false if not.
2349
2350
2351
2352       val get_uri : t -> string
2353
2354       construct an NBD URI for a connection
2355
2356       This makes a best effort attempt to construct an NBD URI which could be
2357       used to connect back to the same server (using nbd_connect_uri(3)).
2358
2359       In some cases there is not enough information in the handle to success‐
2360       fully create a URI (eg. if you connected  with  nbd_connect_socket(3)).
2361       In  such  cases the call returns "NULL" and further diagnostic informa‐
2362       tion is available via nbd_get_errno(3) and nbd_get_error(3) as usual.
2363
2364       Even if a URI is returned it is not guaranteed to work, and it may  not
2365       be optimal.
2366
2367
2368
2369
2370
2371OCamldoc                          2021-10-25                            NBD(3)
Impressum