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