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

NAME

6       NBD - OCaml bindings for libnbd.
7

Module

9       Module   NBD
10

Documentation

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