libvirt/libvirt.mli

   1 (** OCaml bindings for libvirt. *)
   2 (* (C) Copyright 2007-2015 Richard W.M. Jones, Red Hat Inc.
   3    http://libvirt.org/
   4
   5    This library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Lesser General Public
   7    License as published by the Free Software Foundation; either
   8    version 2 of the License, or (at your option) any later version,
   9    with the OCaml linking exception described in ../COPYING.LIB.
  10
  11    This library is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14    Lesser General Public License for more details.
  15
  16    You should have received a copy of the GNU Lesser General Public
  17    License along with this library; if not, write to the Free Software
  18    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
  19 *)
  20
  21 (**
  22    {2 Introduction and examples}
  23
  24    This is a set of bindings for writing OCaml programs to
  25    manage virtual machines through {{:http://libvirt.org/}libvirt}.
  26
  27    {3 Using libvirt interactively}
  28
  29    Using the interactive toplevel:
  30
  31 {v
  32 $ ocaml -I +libvirt
  33         Objective Caml version 3.10.0
  34
  35 # #load "unix.cma";;
  36 # #load "mllibvirt.cma";;
  37 # let name = "test:///default";;
  38 val name : string = "test:///default"
  39 # let conn = Libvirt.Connect.connect_readonly ~name () ;;
  40 val conn : Libvirt.ro Libvirt.Connect.t = <abstr>
  41 # Libvirt.Connect.get_node_info conn;;
  42   : Libvirt.Connect.node_info =
  43 {Libvirt.Connect.model = "i686"; Libvirt.Connect.memory = 3145728L;
  44  Libvirt.Connect.cpus = 16; Libvirt.Connect.mhz = 1400;
  45  Libvirt.Connect.nodes = 2; Libvirt.Connect.sockets = 2;
  46  Libvirt.Connect.cores = 2; Libvirt.Connect.threads = 2}
  47 v}
  48
  49    {3 Compiling libvirt programs}
  50
  51    This command compiles a program to native code:
  52
  53 {v
  54 ocamlopt -I +libvirt mllibvirt.cmxa list_domains.ml -o list_domains
  55 v}
  56
  57    {3 Example: Connect to the hypervisor}
  58
  59    The main modules are {!Libvirt.Connect}, {!Libvirt.Domain} and
  60    {!Libvirt.Network} corresponding respectively to the
  61    {{:http://libvirt.org/html/libvirt-libvirt.html}virConnect*, virDomain* and virNetwork* functions from libvirt}.
  62    For brevity I usually rename these modules like this:
  63
  64 {[
  65 module C = Libvirt.Connect
  66 module D = Libvirt.Domain
  67 module N = Libvirt.Network
  68 ]}
  69
  70    To get a connection handle, assuming a Xen hypervisor:
  71
  72 {[
  73 let name = "xen:///"
  74 let conn = C.connect_readonly ~name ()
  75 ]}
  76
  77    {3 Example: List running domains}
  78
  79 {[
  80 open Printf
  81
  82 let domains = D.get_domains conn [D.ListActive] in
  83 List.iter (
  84   fun dom ->
  85     printf "%8d %s\n%!" (D.get_id dom) (D.get_name dom)
  86 ) domains;
  87 ]}
  88
  89    {3 Example: List inactive domains}
  90
  91 {[
  92 let domains = D.get_domains conn [D.ListInactive] in
  93 List.iter (
  94   fun dom ->
  95     printf "inactive %s\n%!" (D.get_name dom)
  96 ) domains;
  97 ]}
  98
  99    {3 Example: Print node info}
 100
 101 {[
 102 let node_info = C.get_node_info conn in
 103 printf "model = %s\n" node_info.C.model;
 104 printf "memory = %Ld K\n" node_info.C.memory;
 105 printf "cpus = %d\n" node_info.C.cpus;
 106 printf "mhz = %d\n" node_info.C.mhz;
 107 printf "nodes = %d\n" node_info.C.nodes;
 108 printf "sockets = %d\n" node_info.C.sockets;
 109 printf "cores = %d\n" node_info.C.cores;
 110 printf "threads = %d\n%!" node_info.C.threads;
 111
 112 let hostname = C.get_hostname conn in
 113 printf "hostname = %s\n%!" hostname;
 114
 115 let uri = C.get_uri conn in
 116 printf "uri = %s\n%!" uri
 117 ]}
 118
 119 *)
 120
 121
 122 (** {2 Programming issues}
 123
 124     {3 General safety issues}
 125
 126     Memory allocation / automatic garbage collection of all libvirt
 127     objects should be completely safe.  If you find any safety issues
 128     or if your pure OCaml program ever segfaults, please contact the author.
 129
 130     You can force a libvirt object to be freed early by calling
 131     the [close] function on the object.  This shouldn't affect
 132     the safety of garbage collection and should only be used when
 133     you want to explicitly free memory.  Note that explicitly
 134     closing a connection object does nothing if there are still
 135     unclosed domain or network objects referencing it.
 136
 137     Note that even though you hold open (eg) a domain object, that
 138     doesn't mean that the domain (virtual machine) actually exists.
 139     The domain could have been shut down or deleted by another user.
 140     Thus domain objects can raise odd exceptions at any time.
 141     This is just the nature of virtualisation.
 142
 143     {3 Backwards and forwards compatibility}
 144
 145     OCaml-libvirt requires libvirt version 1.0.2 or later. Future
 146     releases of OCaml-libvirt will use newer features of libvirt
 147     and therefore will require later versions of libvirt. It is always
 148     possible to dynamically link your application against a newer
 149     libvirt than OCaml-libvirt was originally compiled against.
 150
 151     {3 Get list of domains and domain infos}
 152
 153     This is a very common operation, and libvirt supports various
 154     different methods to do it.  We have hidden the complexity in a
 155     flexible {!Libvirt.Domain.get_domains} and
 156     {!Libvirt.Domain.get_domains_and_infos} calls which is easy to use and
 157     automatically chooses the most efficient method depending on the
 158     version of libvirt in use.
 159
 160     {3 Threads}
 161
 162     You can issue multiple concurrent libvirt requests in
 163     different threads.  However you must follow this rule:
 164     Each thread must have its own separate libvirt connection, {i or}
 165     you must implement your own mutex scheme to ensure that no
 166     two threads can ever make concurrent calls using the same
 167     libvirt connection.
 168
 169     (Note that multithreaded code is not well tested.  If you find
 170     bugs please report them.)
 171
 172     {3 Initialisation}
 173
 174     Libvirt requires all callers to call virInitialize before
 175     using the library.  This is done automatically for you by
 176     these bindings when the program starts up, and we believe
 177     that the way this is done is safe.
 178
 179     {2 Reference}
 180 *)
 181
 182 type uuid = string
 183     (** This is a "raw" UUID, ie. a packed string of bytes. *)
 184
 185 type xml = string
 186     (** Type of XML (an uninterpreted string of bytes).  Use PXP, expat,
 187         xml-light, etc. if you want to do anything useful with the XML.
 188     *)
 189
 190 type filename = string
 191     (** A filename. *)
 192
 193 val get_version : ?driver:string -> unit -> int * int
 194   (** [get_version ()] returns the library version in the first part
 195       of the tuple, and [0] in the second part.
 196
 197       [get_version ~driver ()] returns the library version in the first
 198       part of the tuple, and the version of the driver called [driver]
 199       in the second part.
 200
 201       The version numbers are encoded as
 202       1,000,000 * major + 1,000 * minor + release.
 203   *)
 204
 205 val uuid_length : int
 206   (** Length of packed UUIDs. *)
 207
 208 val uuid_string_length : int
 209   (** Length of UUID strings. *)
 210
 211 type rw = [`R|`W]
 212 type ro = [`R]
 213     (** These
 214         {{:http://caml.inria.fr/pub/ml-archives/caml-list/2004/07/80683af867cce6bf8fff273973f70c95.en.html}phantom types}
 215         are used to ensure the type-safety of read-only
 216         versus read-write connections.
 217
 218         All connection/domain/etc. objects are marked with
 219         a phantom read-write or read-only type, and trying to
 220         pass a read-only object into a function which could
 221         mutate the object will cause a compile time error.
 222
 223         Each module provides a function like {!Libvirt.Connect.const}
 224         to demote a read-write object into a read-only object.  The
 225         opposite operation is, of course, not allowed.
 226
 227         If you want to handle both read-write and read-only
 228         connections at runtime, use a variant similar to this:
 229 {[
 230 type conn_t =
 231     | No_connection
 232     | Read_only of Libvirt.ro Libvirt.Connect.t
 233     | Read_write of Libvirt.rw Libvirt.Connect.t
 234 ]}
 235     *)
 236
 237 (** {3 Forward definitions}
 238
 239     These definitions are placed here to avoid the need to
 240     use recursive module dependencies.
 241 *)
 242
 243 (** {3 Connections} *)
 244
 245 module Connect :
 246 sig
 247   type 'rw t
 248     (** Connection.  Read-only connections have type [ro Connect.t] and
 249         read-write connections have type [rw Connect.t].
 250       *)
 251
 252   type node_info = {
 253     model : string;                     (** CPU model *)
 254     memory : int64;                     (** memory size in kilobytes *)
 255     cpus : int;                         (** number of active CPUs *)
 256     mhz : int;                          (** expected CPU frequency *)
 257     nodes : int;                        (** number of NUMA nodes (1 = UMA) *)
 258     sockets : int;                      (** number of CPU sockets per node *)
 259     cores : int;                        (** number of cores per socket *)
 260     threads : int;                      (** number of threads per core *)
 261   }
 262
 263   type credential_type =
 264     | CredentialUsername                (** Identity to act as *)
 265     | CredentialAuthname                (** Identify to authorize as *)
 266     | CredentialLanguage                (** RFC 1766 languages, comma separated *)
 267     | CredentialCnonce                  (** client supplies a nonce *)
 268     | CredentialPassphrase              (** Passphrase secret *)
 269     | CredentialEchoprompt              (** Challenge response *)
 270     | CredentialNoechoprompt            (** Challenge response *)
 271     | CredentialRealm                   (** Authentication realm *)
 272     | CredentialExternal                (** Externally managed credential *)
 273
 274   type credential = {
 275     typ : credential_type;              (** The type of credential *)
 276     prompt : string;                    (** Prompt to show to user *)
 277     challenge : string option;          (** Additional challenge to show *)
 278     defresult : string option;          (** Optional default result *)
 279   }
 280
 281   type auth = {
 282     credtype : credential_type list;    (** List of supported credential_type values *)
 283     cb : (credential list -> string option list);
 284     (** Callback used to collect credentials.
 285
 286         The input is a list of all the requested credentials.
 287
 288         The function returns a list of all the results from the
 289         requested credentials, so the number of results {e must} match
 290         the number of input credentials.  Each result is optional,
 291         and in case it is [None] it means there was no result.
 292      *)
 293   }
 294
 295   val connect : ?name:string -> unit -> rw t
 296   val connect_readonly : ?name:string -> unit -> ro t
 297     (** [connect ~name ()] connects to the hypervisor with URI [name].
 298
 299         [connect ()] connects to the default hypervisor.
 300
 301         [connect_readonly] is the same but connects in read-only mode.
 302     *)
 303
 304   val connect_auth : ?name:string -> auth -> rw t
 305   val connect_auth_readonly : ?name:string -> auth -> ro t
 306
 307   val close : [>`R] t -> unit
 308     (** [close conn] closes and frees the connection object in memory.
 309
 310         The connection is automatically closed if it is garbage
 311         collected.  This function just forces it to be closed
 312         and freed right away.
 313     *)
 314
 315   val get_type : [>`R] t -> string
 316     (** Returns the name of the driver (hypervisor). *)
 317
 318   val get_version : [>`R] t -> int
 319     (** Returns the driver version
 320         [major * 1_000_000 + minor * 1000 + release]
 321     *)
 322   val get_hostname : [>`R] t -> string
 323     (** Returns the hostname of the physical server. *)
 324   val get_uri : [>`R] t -> string
 325     (** Returns the canonical connection URI. *)
 326   val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
 327     (** Returns the maximum number of virtual CPUs
 328         supported by a guest VM of a particular type. *)
 329   val list_domains : [>`R] t -> int -> int array
 330     (** [list_domains conn max] returns the running domain IDs,
 331         up to a maximum of [max] entries.
 332
 333         Call {!num_of_domains} first to get a value for [max].
 334
 335         See also:
 336         {!Libvirt.Domain.get_domains},
 337         {!Libvirt.Domain.get_domains_and_infos}.
 338     *)
 339   val num_of_domains : [>`R] t -> int
 340     (** Returns the number of running domains. *)
 341   val get_capabilities : [>`R] t -> xml
 342     (** Returns the hypervisor capabilities (as XML). *)
 343   val num_of_defined_domains : [>`R] t -> int
 344     (** Returns the number of inactive (shutdown) domains. *)
 345   val list_defined_domains : [>`R] t -> int -> string array
 346     (** [list_defined_domains conn max]
 347         returns the names of the inactive domains, up to
 348         a maximum of [max] entries.
 349
 350         Call {!num_of_defined_domains} first to get a value for [max].
 351
 352         See also:
 353         {!Libvirt.Domain.get_domains},
 354         {!Libvirt.Domain.get_domains_and_infos}.
 355     *)
 356   val num_of_networks : [>`R] t -> int
 357     (** Returns the number of networks. *)
 358   val list_networks : [>`R] t -> int -> string array
 359     (** [list_networks conn max]
 360         returns the names of the networks, up to a maximum
 361         of [max] entries.
 362         Call {!num_of_networks} first to get a value for [max].
 363     *)
 364   val num_of_defined_networks : [>`R] t -> int
 365     (** Returns the number of inactive networks. *)
 366   val list_defined_networks : [>`R] t -> int -> string array
 367     (** [list_defined_networks conn max]
 368         returns the names of the inactive networks, up to a maximum
 369         of [max] entries.
 370         Call {!num_of_defined_networks} first to get a value for [max].
 371     *)
 372
 373   val num_of_pools : [>`R] t -> int
 374     (** Returns the number of storage pools. *)
 375   val list_pools : [>`R] t -> int -> string array
 376     (** Return list of storage pools. *)
 377   val num_of_defined_pools : [>`R] t -> int
 378     (** Returns the number of storage pools. *)
 379   val list_defined_pools : [>`R] t -> int -> string array
 380     (** Return list of storage pools. *)
 381
 382     (* The name of this function is inconsistent, but the inconsistency
 383      * is really in libvirt itself.
 384      *)
 385   val get_node_info : [>`R] t -> node_info
 386     (** Return information about the physical server. *)
 387
 388   val node_get_free_memory : [> `R] t -> int64
 389     (**
 390        [node_get_free_memory conn]
 391        returns the amount of free memory (not allocated to any guest)
 392        in the machine.
 393     *)
 394
 395   val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array
 396     (**
 397        [node_get_cells_free_memory conn start max]
 398        returns the amount of free memory on each NUMA cell in kilobytes.
 399        [start] is the first cell for which we return free memory.
 400        [max] is the maximum number of cells for which we return free memory.
 401        Returns an array of up to [max] entries in length.
 402     *)
 403
 404   val maxcpus_of_node_info : node_info -> int
 405     (** Calculate the total number of CPUs supported (but not necessarily
 406         active) in the host.
 407     *)
 408
 409   val cpumaplen : int -> int
 410     (** Calculate the length (in bytes) required to store the complete
 411         CPU map between a single virtual and all physical CPUs of a domain.
 412     *)
 413
 414   val use_cpu : bytes -> int -> unit
 415     (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
 416   val unuse_cpu : bytes -> int -> unit
 417     (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
 418   val cpu_usable : bytes -> int -> int -> int -> bool
 419     (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
 420         [cpu] is usable by [vcpu]. *)
 421
 422   val set_keep_alive : [>`R] t -> int -> int -> unit
 423     (** [set_keep_alive conn interval count] starts sending keepalive
 424         messages after [interval] seconds of inactivity and consider the
 425         connection to be broken when no response is received after [count]
 426         keepalive messages.
 427         Note: the client has to implement and run an event loop to
 428         be able to use keep-alive messages. *)
 429
 430   external const : [>`R] t -> ro t = "%identity"
 431     (** [const conn] turns a read/write connection into a read-only
 432         connection.  Note that the opposite operation is impossible.
 433       *)
 434 end
 435   (** Module dealing with connections.  [Connect.t] is the
 436       connection object. *)
 437
 438 (** {3 Domains} *)
 439
 440 module Domain :
 441 sig
 442   type 'rw t
 443     (** Domain handle.  Read-only handles have type [ro Domain.t] and
 444         read-write handles have type [rw Domain.t].
 445     *)
 446
 447   type state =
 448     | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
 449     | InfoShutdown | InfoShutoff | InfoCrashed
 450
 451   type info = {
 452     state : state;                      (** running state *)
 453     max_mem : int64;                    (** maximum memory in kilobytes *)
 454     memory : int64;                     (** memory used in kilobytes *)
 455     nr_virt_cpu : int;                  (** number of virtual CPUs *)
 456     cpu_time : int64;                   (** CPU time used in nanoseconds *)
 457   }
 458
 459   type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
 460
 461   type vcpu_info = {
 462     number : int;                       (** virtual CPU number *)
 463     vcpu_state : vcpu_state;            (** state *)
 464     vcpu_time : int64;                  (** CPU time used in nanoseconds *)
 465     cpu : int;                          (** real CPU number, -1 if offline *)
 466   }
 467
 468   type domain_create_flag =
 469   | START_PAUSED                        (** Launch guest in paused state *)
 470   | START_AUTODESTROY                   (** Automatically kill guest on close *)
 471   | START_BYPASS_CACHE                  (** Avoid filesystem cache pollution *)
 472   | START_FORCE_BOOT                    (** Discard any managed save *)
 473   | START_VALIDATE                      (** Validate XML against schema *)
 474
 475   type sched_param = string * sched_param_value
 476   and sched_param_value =
 477     | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
 478     | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
 479     | SchedFieldFloat of float | SchedFieldBool of bool
 480
 481   type typed_param = string * typed_param_value
 482   and typed_param_value =
 483     | TypedFieldInt32 of int32 | TypedFieldUInt32 of int32
 484     | TypedFieldInt64 of int64 | TypedFieldUInt64 of int64
 485     | TypedFieldFloat of float | TypedFieldBool of bool
 486     | TypedFieldString of string
 487
 488   type migrate_flag = Live
 489
 490   type memory_flag = Virtual
 491
 492   type list_flag =
 493     | ListActive
 494     | ListInactive
 495     | ListAll
 496
 497   type block_stats = {
 498     rd_req : int64;
 499     rd_bytes : int64;
 500     wr_req : int64;
 501     wr_bytes : int64;
 502     errs : int64;
 503   }
 504
 505   type interface_stats = {
 506     rx_bytes : int64;
 507     rx_packets : int64;
 508     rx_errs : int64;
 509     rx_drop : int64;
 510     tx_bytes : int64;
 511     tx_packets : int64;
 512     tx_errs : int64;
 513     tx_drop : int64;
 514   }
 515
 516   type get_all_domain_stats_flag =
 517     | GetAllDomainsStatsActive
 518     | GetAllDomainsStatsInactive
 519     | GetAllDomainsStatsOther
 520     | GetAllDomainsStatsPaused
 521     | GetAllDomainsStatsPersistent
 522     | GetAllDomainsStatsRunning
 523     | GetAllDomainsStatsShutoff
 524     | GetAllDomainsStatsTransient
 525     | GetAllDomainsStatsBacking
 526     | GetAllDomainsStatsEnforceStats
 527
 528   type stats_type =
 529     | StatsState | StatsCpuTotal | StatsBalloon | StatsVcpu
 530     | StatsInterface | StatsBlock | StatsPerf
 531
 532   type domain_stats_record = {
 533     dom_uuid : uuid;
 534     params : typed_param array;
 535   }
 536
 537   type xml_desc_flag =
 538     | XmlSecure                 (* dump security sensitive information too *)
 539     | XmlInactive               (* dump inactive domain information *)
 540     | XmlUpdateCPU              (* update guest CPU requirements according to host CPU *)
 541     | XmlMigratable             (* dump XML suitable for migration *)
 542
 543   val max_peek : [>`R] t -> int
 544     (** Maximum size supported by the {!block_peek} and {!memory_peek}
 545         functions.  If you want to peek more than this then you must
 546         break your request into chunks. *)
 547
 548   val create_linux : [>`W] Connect.t -> xml -> rw t
 549     (** Create a new guest domain (not necessarily a Linux one)
 550         from the given XML.  Use {!create_xml} instead.
 551     *)
 552   val create_xml : [>`W] Connect.t -> xml -> domain_create_flag list -> rw t
 553     (** Create a new guest domain from the given XML. *)
 554   val lookup_by_id : 'a Connect.t -> int -> 'a t
 555     (** Lookup a domain by ID. *)
 556   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
 557     (** Lookup a domain by UUID.  This uses the packed byte array UUID. *)
 558   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
 559     (** Lookup a domain by (string) UUID. *)
 560   val lookup_by_name : 'a Connect.t -> string -> 'a t
 561     (** Lookup a domain by name. *)
 562   val destroy : [>`W] t -> unit
 563     (** Abruptly destroy a domain. *)
 564   val free : [>`R] t -> unit
 565     (** [free domain] frees the domain object in memory.
 566
 567         The domain object is automatically freed if it is garbage
 568         collected.  This function just forces it to be freed right
 569         away.
 570     *)
 571
 572   val suspend : [>`W] t -> unit
 573     (** Suspend a domain. *)
 574   val resume : [>`W] t -> unit
 575     (** Resume a domain. *)
 576   val save : [>`W] t -> filename -> unit
 577     (** Suspend a domain, then save it to the file. *)
 578   val restore : [>`W] Connect.t -> filename -> unit
 579     (** Restore a domain from a file. *)
 580   val core_dump : [>`W] t -> filename -> unit
 581     (** Force a domain to core dump to the named file. *)
 582   val shutdown : [>`W] t -> unit
 583     (** Shutdown a domain. *)
 584   val reboot : [>`W] t -> unit
 585     (** Reboot a domain. *)
 586   val get_name : [>`R] t -> string
 587     (** Get the domain name. *)
 588   val get_uuid : [>`R] t -> uuid
 589     (** Get the domain UUID (as a packed byte array). *)
 590   val get_uuid_string : [>`R] t -> string
 591     (** Get the domain UUID (as a printable string). *)
 592   val get_id : [>`R] t -> int
 593     (** [get_id dom] returns the ID of the domain.  In most cases
 594         this returns [-1] if the domain is not running. *)
 595   val get_os_type : [>`R] t -> string
 596     (** Get the operating system type. *)
 597   val get_max_memory : [>`R] t -> int64
 598     (** Get the maximum memory allocation. *)
 599   val set_max_memory : [>`W] t -> int64 -> unit
 600     (** Set the maximum memory allocation. *)
 601   val set_memory : [>`W] t -> int64 -> unit
 602     (** Set the normal memory allocation. *)
 603   val get_info : [>`R] t -> info
 604     (** Get information about a domain. *)
 605   val get_xml_desc : [>`R] t -> xml
 606     (** Get the XML description of a domain. *)
 607   val get_xml_desc_flags : [>`W] t -> xml_desc_flag list -> xml
 608     (** Get the XML description of a domain, with the possibility
 609         to specify flags. *)
 610   val get_scheduler_type : [>`R] t -> string * int
 611     (** Get the scheduler type. *)
 612   val get_scheduler_parameters : [>`R] t -> int -> sched_param array
 613     (** Get the array of scheduler parameters. *)
 614   val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
 615     (** Set the array of scheduler parameters. *)
 616   val define_xml : [>`W] Connect.t -> xml -> rw t
 617     (** Define a new domain (but don't start it up) from the XML. *)
 618   val undefine : [>`W] t -> unit
 619     (** Undefine a domain - removes its configuration. *)
 620   val create : [>`W] t -> unit
 621     (** Launch a defined (inactive) domain. *)
 622   val get_autostart : [>`R] t -> bool
 623     (** Get the autostart flag for a domain. *)
 624   val set_autostart : [>`W] t -> bool -> unit
 625     (** Set the autostart flag for a domain. *)
 626   val set_vcpus : [>`W] t -> int -> unit
 627     (** Change the number of vCPUs available to a domain. *)
 628   val pin_vcpu : [>`W] t -> int -> string -> unit
 629     (** [pin_vcpu dom vcpu bitmap] pins a domain vCPU to a bitmap of physical
 630         CPUs.  See the libvirt documentation for details of the
 631         layout of the bitmap. *)
 632   val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
 633     (** [get_vcpus dom maxinfo maplen] returns the pinning information
 634         for a domain.  See the libvirt documentation for details
 635         of the array and bitmap returned from this function.
 636     *)
 637   val get_cpu_stats : [>`R] t -> typed_param list array
 638     (** [get_pcpu_stats dom] returns the physical CPU stats
 639         for a domain.  See the libvirt documentation for details.
 640     *)
 641   val get_max_vcpus : [>`R] t -> int
 642     (** Returns the maximum number of vCPUs supported for this domain. *)
 643   val attach_device : [>`W] t -> xml -> unit
 644     (** Attach a device (described by the device XML) to a domain. *)
 645   val detach_device : [>`W] t -> xml -> unit
 646     (** Detach a device (described by the device XML) from a domain. *)
 647
 648   val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
 649     ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
 650     (** [migrate dom dconn flags ()] migrates a domain to a
 651         destination host described by [dconn].
 652
 653         The optional flag [?dname] is used to rename the domain.
 654
 655         The optional flag [?uri] is used to route the migration.
 656
 657         The optional flag [?bandwidth] is used to limit the bandwidth
 658         used for migration (in Mbps). *)
 659
 660   val block_stats : [>`R] t -> string -> block_stats
 661     (** Returns block device stats. *)
 662   val interface_stats : [>`R] t -> string -> interface_stats
 663     (** Returns network interface stats. *)
 664
 665   val block_peek : [>`W] t -> string -> int64 -> int -> string -> int -> unit
 666     (** [block_peek dom path offset size buf boff] reads [size] bytes at
 667         [offset] in the domain's [path] block device.
 668
 669         If successful then the data is written into [buf] starting
 670         at offset [boff], for [size] bytes.
 671
 672         See also {!max_peek}. *)
 673   val memory_peek : [>`W] t -> memory_flag list -> int64 -> int ->
 674     string -> int -> unit
 675     (** [memory_peek dom Virtual offset size] reads [size] bytes
 676         at [offset] in the domain's virtual memory.
 677
 678         If successful then the data is written into [buf] starting
 679         at offset [boff], for [size] bytes.
 680
 681         See also {!max_peek}. *)
 682
 683   external get_all_domain_stats : [>`R] Connect.t -> stats_type list -> get_all_domain_stats_flag list -> domain_stats_record array = "ocaml_libvirt_domain_get_all_domain_stats"
 684     (** [get_all_domain_stats conn stats flags] allows you to read
 685         all stats across multiple/all domains in a single call.
 686
 687         See the libvirt documentation for
 688         [virConnectGetAllDomainStats]. *)
 689
 690   external const : [>`R] t -> ro t = "%identity"
 691     (** [const dom] turns a read/write domain handle into a read-only
 692         domain handle.  Note that the opposite operation is impossible.
 693       *)
 694
 695   val get_domains : ([>`R] as 'a) Connect.t -> list_flag list -> 'a t list
 696     (** Get the active and/or inactive domains using the most
 697         efficient method available.
 698
 699         See also:
 700         {!get_domains_and_infos},
 701         {!Connect.list_domains},
 702         {!Connect.list_defined_domains}.
 703   *)
 704
 705   val get_domains_and_infos : ([>`R] as 'a) Connect.t -> list_flag list ->
 706     ('a t * info) list
 707     (** This gets the active and/or inactive domains and the
 708         domain info for each one using the most efficient
 709         method available.
 710
 711         See also:
 712         {!get_domains},
 713         {!Connect.list_domains},
 714         {!Connect.list_defined_domains},
 715         {!get_info}.
 716     *)
 717
 718 end
 719   (** Module dealing with domains.  [Domain.t] is the
 720       domain object. *)
 721
 722 module Event :
 723 sig
 724
 725   module Defined : sig
 726     type t = [
 727       | `Added          (** Newly created config file *)
 728       | `Updated        (** Changed config file *)
 729       | `Unknown of int
 730     ]
 731
 732     val to_string: t -> string
 733   end
 734
 735   module Undefined : sig
 736     type t = [
 737       | `Removed        (** Deleted the config file *)
 738       | `Unknown of int
 739     ]
 740
 741     val to_string: t -> string
 742   end
 743
 744   module Started : sig
 745     type t = [
 746       | `Booted         (** Normal startup from boot *)
 747       | `Migrated       (** Incoming migration from another host *)
 748       | `Restored       (** Restored from a state file *)
 749       | `FromSnapshot   (** Restored from snapshot *)
 750       | `Wakeup         (** Started due to wakeup event *)
 751       | `Unknown of int
 752     ]
 753
 754     val to_string: t -> string
 755   end
 756
 757   module Suspended : sig
 758     type t = [
 759       | `Paused        (** Normal suspend due to admin pause *)
 760       | `Migrated      (** Suspended for offline migration *)
 761       | `IOError       (** Suspended due to a disk I/O error *)
 762       | `Watchdog      (** Suspended due to a watchdog firing *)
 763       | `Restored      (** Restored from paused state file *)
 764       | `FromSnapshot  (** Restored from paused snapshot *)
 765       | `APIError      (** suspended after failure during libvirt API call *)
 766       | `Unknown of int
 767     ]
 768
 769     val to_string: t -> string
 770   end
 771
 772   module Resumed : sig
 773     type t = [
 774       | `Unpaused      (** Normal resume due to admin unpause *)
 775       | `Migrated      (** Resumed for completion of migration *)
 776       | `FromSnapshot  (** Resumed from snapshot *)
 777       | `Unknown of int
 778     ]
 779
 780     val to_string: t -> string
 781   end
 782
 783   module Stopped : sig
 784     type t = [
 785       | `Shutdown     (** Normal shutdown *)
 786       | `Destroyed    (** Forced poweroff from host *)
 787       | `Crashed      (** Guest crashed *)
 788       | `Migrated     (** Migrated off to another host *)
 789       | `Saved        (** Saved to a state file *)
 790       | `Failed       (** Host emulator/mgmt failed *)
 791       | `FromSnapshot (** offline snapshot loaded *)
 792       | `Unknown of int
 793     ]
 794
 795     val to_string: t -> string
 796   end
 797
 798   module PM_suspended : sig
 799     type t = [
 800       | `Memory       (** Guest was PM suspended to memory *)
 801       | `Disk         (** Guest was PM suspended to disk *)
 802       | `Unknown of int
 803     ]
 804
 805     val to_string: t -> string
 806   end
 807
 808   module Lifecycle : sig
 809     type t = [
 810       | `Defined of Defined.t
 811       | `Undefined of Undefined.t
 812       | `Started of Started.t
 813       | `Suspended of Suspended.t
 814       | `Resumed of Resumed.t
 815       | `Stopped of Stopped.t
 816       | `Shutdown (* no detail defined yet *)
 817       | `PMSuspended of PM_suspended.t
 818       | `Unknown of int
 819     ]
 820
 821     val to_string: t -> string
 822   end
 823
 824   module Reboot : sig
 825     type t = unit
 826
 827     val to_string: t -> string
 828   end
 829
 830   module Rtc_change : sig
 831     type t = int64
 832
 833     val to_string: t -> string
 834   end
 835
 836   module Watchdog : sig
 837     type t = [
 838       | `None           (** No action, watchdog ignored *)
 839       | `Pause          (** Guest CPUs are paused *)
 840       | `Reset          (** Guest CPUs are reset *)
 841       | `Poweroff       (** Guest is forcably powered off *)
 842       | `Shutdown       (** Guest is requested to gracefully shutdown *)
 843       | `Debug          (** No action, a debug message logged *)
 844       | `Unknown of int (** newer libvirt *)
 845     ]
 846
 847     val to_string: t -> string
 848   end
 849
 850   module Io_error : sig
 851     (** Represents both IOError and IOErrorReason *)
 852     type action = [
 853       | `None           (** No action, IO error ignored *)
 854       | `Pause          (** Guest CPUs are paused *)
 855       | `Report         (** IO error reported to guest OS *)
 856       | `Unknown of int (** newer libvirt *)
 857     ]
 858
 859     type t = {
 860       src_path: string option;  (** The host file on which the I/O error occurred *)
 861       dev_alias: string option; (** The guest device alias associated with the path *)
 862       action: action;    (** The action that is to be taken due to the IO error *)
 863       reason: string option;    (** The cause of the IO error *)
 864     }
 865
 866     val to_string: t -> string
 867   end
 868
 869   module Graphics_address : sig
 870     type family = [
 871       | `Ipv4           (** IPv4 address *)
 872       | `Ipv6           (** IPv6 address *)
 873       | `Unix           (** UNIX socket path *)
 874       | `Unknown of int (** newer libvirt *)
 875     ]
 876
 877     type t = {
 878       family: family;         (** Address family *)
 879       node: string option;    (** Address of node (eg IP address, or UNIX path *)
 880       service: string option; (** Service name/number (eg TCP port, or NULL) *)
 881     }
 882
 883     val to_string: t -> string
 884   end
 885
 886   module Graphics_subject : sig
 887     type identity = {
 888       ty: string option;   (** Type of identity *)
 889       name: string option; (** Identity value *)
 890     }
 891
 892     type t = identity list
 893
 894     val to_string: t -> string
 895   end
 896
 897   module Graphics : sig
 898     type phase = [
 899       | `Connect        (** Initial socket connection established *)
 900       | `Initialize     (** Authentication & setup completed *)
 901       | `Disconnect     (** Final socket disconnection *)
 902       | `Unknown of int (** newer libvirt *)
 903     ]
 904
 905     type t = {
 906       phase: phase;                (** the phase of the connection *)
 907       local: Graphics_address.t;   (** the local server address *)
 908       remote: Graphics_address.t;  (** the remote client address *)
 909       auth_scheme: string option;  (** the authentication scheme activated *)
 910       subject: Graphics_subject.t; (** the authenticated subject (user) *)
 911     }
 912
 913     val to_string: t -> string
 914   end
 915
 916   module Control_error : sig
 917     type t = unit
 918
 919     val to_string: t -> string
 920   end
 921
 922   module Block_job : sig
 923     type ty = [
 924       | `KnownUnknown (** explicitly named UNKNOWN in the spec *)
 925       | `Pull
 926       | `Copy
 927       | `Commit
 928       | `Unknown of int
 929     ]
 930
 931     type status = [
 932       | `Completed
 933       | `Failed
 934       | `Cancelled
 935       | `Ready
 936       | `Unknown of int
 937     ]
 938
 939     type t = {
 940       disk: string option; (** fully-qualified name of the affected disk *)
 941       ty: ty;              (** type of block job *)
 942       status: status;      (** final status of the operation *)
 943     }
 944
 945     val to_string: t -> string
 946   end
 947
 948   module Disk_change : sig
 949     type reason = [
 950       | `MissingOnStart
 951       | `Unknown of int
 952     ]
 953
 954     type t = {
 955       old_src_path: string option; (** old source path *)
 956       new_src_path: string option; (** new source path *)
 957       dev_alias: string option;    (** device alias name *)
 958       reason: reason;              (** reason why this callback was called *)
 959     }
 960
 961     val to_string: t -> string
 962   end
 963
 964   module Tray_change : sig
 965     type reason = [
 966       | `Open
 967       | `Close
 968       | `Unknown of int
 969     ]
 970
 971     type t = {
 972       dev_alias: string option; (** device alias *)
 973       reason: reason;           (** why the tray status was changed *)
 974     }
 975
 976     val to_string: t -> string
 977   end
 978
 979   module PM_wakeup : sig
 980     type reason = [
 981       | `Unknown of int
 982     ]
 983
 984     type t = reason
 985
 986     val to_string: t -> string
 987   end
 988
 989   module PM_suspend : sig
 990     type reason = [
 991       | `Unknown of int
 992     ]
 993
 994     type t = reason
 995
 996     val to_string: t -> string
 997   end
 998
 999   module Balloon_change : sig
1000     type t = int64
1001
1002     val to_string: t -> string
1003   end
1004
1005   module PM_suspend_disk : sig
1006     type reason = [
1007       | `Unknown of int
1008     ]
1009
1010     type t = reason
1011
1012     val to_string: t -> string
1013   end
1014
1015
1016   type callback =
1017     | Lifecycle     of ([`R] Domain.t -> Lifecycle.t -> unit)
1018     | Reboot        of ([`R] Domain.t -> Reboot.t -> unit)
1019     | RtcChange     of ([`R] Domain.t -> Rtc_change.t -> unit)
1020     | Watchdog      of ([`R] Domain.t -> Watchdog.t -> unit)
1021     | IOError       of ([`R] Domain.t -> Io_error.t -> unit)
1022     | Graphics      of ([`R] Domain.t -> Graphics.t -> unit)
1023     | IOErrorReason of ([`R] Domain.t -> Io_error.t -> unit)
1024     | ControlError  of ([`R] Domain.t -> Control_error.t -> unit)
1025     | BlockJob      of ([`R] Domain.t -> Block_job.t -> unit)
1026     | DiskChange    of ([`R] Domain.t -> Disk_change.t -> unit)
1027     | TrayChange    of ([`R] Domain.t -> Tray_change.t -> unit)
1028     | PMWakeUp      of ([`R] Domain.t -> PM_wakeup.t -> unit)
1029     | PMSuspend     of ([`R] Domain.t -> PM_suspend.t -> unit)
1030     | BalloonChange of ([`R] Domain.t -> Balloon_change.t -> unit)
1031     | PMSuspendDisk of ([`R] Domain.t -> PM_suspend_disk.t -> unit)
1032
1033     (** type of a registered call back function *)
1034
1035   val register_default_impl : unit -> unit
1036     (** Registers the default event loop based on poll(). This
1037         must be done before connections are opened.
1038
1039         Once registered call run_default_impl in a loop. *)
1040
1041   val run_default_impl : unit -> unit
1042     (** Runs one iteration of the event loop. Applications will
1043         generally want to have a thread which invokes this in an
1044         infinite loop. *)
1045
1046   type callback_id
1047     (** an individual event registration *)
1048
1049   val register_any : 'a Connect.t -> ?dom:'a Domain.t -> callback -> callback_id
1050     (** [register_any con ?dom callback] registers [callback]
1051         to receive notification of arbitrary domain events. Return
1052         a registration id which can be used in [deregister_any].
1053
1054         If [?dom] is None then register for this kind of event on
1055         all domains. If [dom] is [Some d] then register for this
1056         kind of event only on [d].
1057     *)
1058
1059   val deregister_any : 'a Connect.t -> callback_id -> unit
1060     (** [deregister_any con id] deregisters the previously registered
1061         callback with id [id]. *)
1062
1063   type timer_id
1064     (** an individual timer event *)
1065
1066   val add_timeout : 'a Connect.t -> int -> (unit -> unit) -> timer_id
1067     (** [add_timeout con ms cb] registers [cb] as a timeout callback
1068         which will be called every [ms] milliseconds *)
1069
1070   val remove_timeout : 'a Connect.t -> timer_id -> unit
1071     (** [remove_timeout con t] deregisters timeout callback [t]. *)
1072
1073 end
1074   (** Module dealing with events generated by domain
1075       state changes. *)
1076
1077 (** {3 Networks} *)
1078
1079 module Network :
1080 sig
1081   type 'rw t
1082     (** Network handle.  Read-only handles have type [ro Network.t] and
1083         read-write handles have type [rw Network.t].
1084     *)
1085
1086   val lookup_by_name : 'a Connect.t -> string -> 'a t
1087     (** Lookup a network by name. *)
1088   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
1089     (** Lookup a network by (packed) UUID. *)
1090   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
1091     (** Lookup a network by UUID string. *)
1092   val create_xml : [>`W] Connect.t -> xml -> rw t
1093     (** Create a network. *)
1094   val define_xml : [>`W] Connect.t -> xml -> rw t
1095     (** Define but don't activate a network. *)
1096   val undefine : [>`W] t -> unit
1097     (** Undefine configuration of a network. *)
1098   val create : [>`W] t -> unit
1099     (** Start up a defined (inactive) network. *)
1100   val destroy : [>`W] t -> unit
1101     (** Destroy a network. *)
1102   val free : [>`R] t -> unit
1103     (** [free network] frees the network object in memory.
1104
1105         The network object is automatically freed if it is garbage
1106         collected.  This function just forces it to be freed right
1107         away.
1108     *)
1109
1110   val get_name : [>`R] t -> string
1111     (** Get network name. *)
1112   val get_uuid : [>`R] t -> uuid
1113     (** Get network packed UUID. *)
1114   val get_uuid_string : [>`R] t -> string
1115     (** Get network UUID as a printable string. *)
1116   val get_xml_desc : [>`R] t -> xml
1117     (** Get XML description of a network. *)
1118   val get_bridge_name : [>`R] t -> string
1119     (** Get bridge device name of a network. *)
1120   val get_autostart : [>`R] t -> bool
1121     (** Get the autostart flag for a network. *)
1122   val set_autostart : [>`W] t -> bool -> unit
1123     (** Set the autostart flag for a network. *)
1124
1125   external const : [>`R] t -> ro t = "%identity"
1126     (** [const network] turns a read/write network handle into a read-only
1127         network handle.  Note that the opposite operation is impossible.
1128       *)
1129 end
1130   (** Module dealing with networks.  [Network.t] is the
1131       network object. *)
1132
1133 (** {3 Storage pools} *)
1134
1135 module Pool :
1136 sig
1137   type 'rw t
1138     (** Storage pool handle. *)
1139
1140   type pool_state = Inactive | Building | Running | Degraded
1141     (** State of the storage pool. *)
1142
1143   type pool_build_flags = New | Repair | Resize
1144     (** Flags for creating a storage pool. *)
1145
1146   type pool_delete_flags = Normal | Zeroed
1147     (** Flags for deleting a storage pool. *)
1148
1149   type pool_info = {
1150     state : pool_state;                 (** Pool state. *)
1151     capacity : int64;                   (** Logical size in bytes. *)
1152     allocation : int64;                 (** Currently allocated in bytes. *)
1153     available : int64;                  (** Remaining free space bytes. *)
1154   }
1155
1156   val lookup_by_name : 'a Connect.t -> string -> 'a t
1157   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
1158   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
1159     (** Look up a storage pool by name, UUID or UUID string. *)
1160
1161   val create_xml : [>`W] Connect.t -> xml -> rw t
1162     (** Create a storage pool. *)
1163   val define_xml : [>`W] Connect.t -> xml -> rw t
1164     (** Define but don't activate a storage pool. *)
1165   val build : [>`W] t -> pool_build_flags -> unit
1166     (** Build a storage pool. *)
1167   val undefine : [>`W] t -> unit
1168     (** Undefine configuration of a storage pool. *)
1169   val create : [>`W] t -> unit
1170     (** Start up a defined (inactive) storage pool. *)
1171   val destroy : [>`W] t -> unit
1172     (** Destroy a storage pool. *)
1173   val delete : [>`W] t -> unit
1174     (** Delete a storage pool. *)
1175   val free : [>`R] t -> unit
1176     (** Free a storage pool object in memory.
1177
1178         The storage pool object is automatically freed if it is garbage
1179         collected.  This function just forces it to be freed right
1180         away.
1181     *)
1182   val refresh : [`R] t -> unit
1183     (** Refresh the list of volumes in the storage pool. *)
1184
1185   val get_name : [`R] t -> string
1186     (** Name of the pool. *)
1187   val get_uuid : [`R] t -> uuid
1188     (** Get the UUID (as a packed byte array). *)
1189   val get_uuid_string : [`R] t -> string
1190     (** Get the UUID (as a printable string). *)
1191   val get_info : [`R] t -> pool_info
1192     (** Get information about the pool. *)
1193   val get_xml_desc : [`R] t -> xml
1194     (** Get the XML description. *)
1195   val get_autostart : [`R] t -> bool
1196     (** Get the autostart flag for the storage pool. *)
1197   val set_autostart : [>`W] t -> bool -> unit
1198     (** Set the autostart flag for the storage pool. *)
1199
1200   val num_of_volumes : [`R] t -> int
1201     (** Returns the number of storage volumes within the storage pool. *)
1202   val list_volumes : [`R] t -> int -> string array
1203     (** Return list of storage volumes. *)
1204
1205   external const : [>`R] t -> ro t = "%identity"
1206     (** [const conn] turns a read/write storage pool into a read-only
1207         pool.  Note that the opposite operation is impossible.
1208       *)
1209 end
1210   (** Module dealing with storage pools. *)
1211
1212 (** {3 Storage volumes} *)
1213
1214 module Volume :
1215 sig
1216   type 'rw t
1217     (** Storage volume handle. *)
1218
1219   type vol_type = File | Block
1220     (** Type of a storage volume. *)
1221
1222   type vol_delete_flags = Normal | Zeroed
1223     (** Flags for deleting a storage volume. *)
1224
1225   type vol_info = {
1226     typ : vol_type;                     (** Type of storage volume. *)
1227     capacity : int64;                   (** Logical size in bytes. *)
1228     allocation : int64;                 (** Currently allocated in bytes. *)
1229   }
1230
1231   val lookup_by_name : 'a Pool.t -> string -> 'a t
1232   val lookup_by_key : 'a Connect.t -> string -> 'a t
1233   val lookup_by_path : 'a Connect.t -> string -> 'a t
1234     (** Look up a storage volume by name, key or path volume. *)
1235
1236   val pool_of_volume : 'a t -> 'a Pool.t
1237     (** Get the storage pool containing this volume. *)
1238
1239   val get_name : [`R] t -> string
1240     (** Name of the volume. *)
1241   val get_key : [`R] t -> string
1242     (** Key of the volume. *)
1243   val get_path : [`R] t -> string
1244     (** Path of the volume. *)
1245   val get_info : [`R] t -> vol_info
1246     (** Get information about the storage volume. *)
1247   val get_xml_desc : [`R] t -> xml
1248     (** Get the XML description. *)
1249
1250   val create_xml : [>`W] Pool.t -> xml -> unit
1251     (** Create a storage volume. *)
1252   val delete : [>`W] t -> vol_delete_flags -> unit
1253     (** Delete a storage volume. *)
1254   val free : [>`R] t -> unit
1255     (** Free a storage volume object in memory.
1256
1257         The storage volume object is automatically freed if it is garbage
1258         collected.  This function just forces it to be freed right
1259         away.
1260     *)
1261
1262   external const : [>`R] t -> ro t = "%identity"
1263     (** [const conn] turns a read/write storage volume into a read-only
1264         volume.  Note that the opposite operation is impossible.
1265       *)
1266 end
1267   (** Module dealing with storage volumes. *)
1268
1269 (** {3 Error handling and exceptions} *)
1270
1271 module Virterror :
1272 sig
1273   type code =
1274     | VIR_ERR_OK
1275     | VIR_ERR_INTERNAL_ERROR
1276     | VIR_ERR_NO_MEMORY
1277     | VIR_ERR_NO_SUPPORT
1278     | VIR_ERR_UNKNOWN_HOST
1279     | VIR_ERR_NO_CONNECT
1280     | VIR_ERR_INVALID_CONN
1281     | VIR_ERR_INVALID_DOMAIN
1282     | VIR_ERR_INVALID_ARG
1283     | VIR_ERR_OPERATION_FAILED
1284     | VIR_ERR_GET_FAILED
1285     | VIR_ERR_POST_FAILED
1286     | VIR_ERR_HTTP_ERROR
1287     | VIR_ERR_SEXPR_SERIAL
1288     | VIR_ERR_NO_XEN
1289     | VIR_ERR_XEN_CALL
1290     | VIR_ERR_OS_TYPE
1291     | VIR_ERR_NO_KERNEL
1292     | VIR_ERR_NO_ROOT
1293     | VIR_ERR_NO_SOURCE
1294     | VIR_ERR_NO_TARGET
1295     | VIR_ERR_NO_NAME
1296     | VIR_ERR_NO_OS
1297     | VIR_ERR_NO_DEVICE
1298     | VIR_ERR_NO_XENSTORE
1299     | VIR_ERR_DRIVER_FULL
1300     | VIR_ERR_CALL_FAILED
1301     | VIR_ERR_XML_ERROR
1302     | VIR_ERR_DOM_EXIST
1303     | VIR_ERR_OPERATION_DENIED
1304     | VIR_ERR_OPEN_FAILED
1305     | VIR_ERR_READ_FAILED
1306     | VIR_ERR_PARSE_FAILED
1307     | VIR_ERR_CONF_SYNTAX
1308     | VIR_ERR_WRITE_FAILED
1309     | VIR_ERR_XML_DETAIL
1310     | VIR_ERR_INVALID_NETWORK
1311     | VIR_ERR_NETWORK_EXIST
1312     | VIR_ERR_SYSTEM_ERROR
1313     | VIR_ERR_RPC
1314     | VIR_ERR_GNUTLS_ERROR
1315     | VIR_WAR_NO_NETWORK
1316     | VIR_ERR_NO_DOMAIN
1317     | VIR_ERR_NO_NETWORK
1318     | VIR_ERR_INVALID_MAC
1319     | VIR_ERR_AUTH_FAILED
1320     | VIR_ERR_INVALID_STORAGE_POOL
1321     | VIR_ERR_INVALID_STORAGE_VOL
1322     | VIR_WAR_NO_STORAGE
1323     | VIR_ERR_NO_STORAGE_POOL
1324     | VIR_ERR_NO_STORAGE_VOL
1325     | VIR_WAR_NO_NODE
1326     | VIR_ERR_INVALID_NODE_DEVICE
1327     | VIR_ERR_NO_NODE_DEVICE
1328     | VIR_ERR_NO_SECURITY_MODEL
1329     | VIR_ERR_OPERATION_INVALID
1330     | VIR_WAR_NO_INTERFACE
1331     | VIR_ERR_NO_INTERFACE
1332     | VIR_ERR_INVALID_INTERFACE
1333     | VIR_ERR_MULTIPLE_INTERFACES
1334     | VIR_WAR_NO_NWFILTER
1335     | VIR_ERR_INVALID_NWFILTER
1336     | VIR_ERR_NO_NWFILTER
1337     | VIR_ERR_BUILD_FIREWALL
1338     | VIR_WAR_NO_SECRET
1339     | VIR_ERR_INVALID_SECRET
1340     | VIR_ERR_NO_SECRET
1341     | VIR_ERR_CONFIG_UNSUPPORTED
1342     | VIR_ERR_OPERATION_TIMEOUT
1343     | VIR_ERR_MIGRATE_PERSIST_FAILED
1344     | VIR_ERR_HOOK_SCRIPT_FAILED
1345     | VIR_ERR_INVALID_DOMAIN_SNAPSHOT
1346     | VIR_ERR_NO_DOMAIN_SNAPSHOT
1347     | VIR_ERR_INVALID_STREAM
1348     | VIR_ERR_ARGUMENT_UNSUPPORTED
1349     | VIR_ERR_STORAGE_PROBE_FAILED
1350     | VIR_ERR_STORAGE_POOL_BUILT
1351     | VIR_ERR_SNAPSHOT_REVERT_RISKY
1352     | VIR_ERR_OPERATION_ABORTED
1353     | VIR_ERR_AUTH_CANCELLED
1354     | VIR_ERR_NO_DOMAIN_METADATA
1355     | VIR_ERR_MIGRATE_UNSAFE
1356     | VIR_ERR_OVERFLOW
1357     | VIR_ERR_BLOCK_COPY_ACTIVE
1358     | VIR_ERR_OPERATION_UNSUPPORTED
1359     | VIR_ERR_SSH
1360     | VIR_ERR_AGENT_UNRESPONSIVE
1361     | VIR_ERR_RESOURCE_BUSY
1362     | VIR_ERR_ACCESS_DENIED
1363     | VIR_ERR_DBUS_SERVICE
1364     | VIR_ERR_STORAGE_VOL_EXIST
1365     | VIR_ERR_CPU_INCOMPATIBLE
1366     | VIR_ERR_XML_INVALID_SCHEMA
1367     | VIR_ERR_MIGRATE_FINISH_OK
1368     | VIR_ERR_AUTH_UNAVAILABLE
1369     | VIR_ERR_NO_SERVER
1370     | VIR_ERR_NO_CLIENT
1371     | VIR_ERR_AGENT_UNSYNCED
1372     | VIR_ERR_LIBSSH
1373     | VIR_ERR_DEVICE_MISSING
1374     | VIR_ERR_INVALID_NWFILTER_BINDING
1375     | VIR_ERR_NO_NWFILTER_BINDING
1376         (* ^^ NB: If you add a variant you MUST edit
1377            libvirt_c_epilogue.c:MAX_VIR_* *)
1378     | VIR_ERR_UNKNOWN of int
1379         (** See [<libvirt/virterror.h>] for meaning of these codes. *)
1380
1381   val string_of_code : code -> string
1382
1383   type domain =
1384     | VIR_FROM_NONE
1385     | VIR_FROM_XEN
1386     | VIR_FROM_XEND
1387     | VIR_FROM_XENSTORE
1388     | VIR_FROM_SEXPR
1389     | VIR_FROM_XML
1390     | VIR_FROM_DOM
1391     | VIR_FROM_RPC
1392     | VIR_FROM_PROXY
1393     | VIR_FROM_CONF
1394     | VIR_FROM_QEMU
1395     | VIR_FROM_NET
1396     | VIR_FROM_TEST
1397     | VIR_FROM_REMOTE
1398     | VIR_FROM_OPENVZ
1399     | VIR_FROM_XENXM
1400     | VIR_FROM_STATS_LINUX
1401     | VIR_FROM_LXC
1402     | VIR_FROM_STORAGE
1403     | VIR_FROM_NETWORK
1404     | VIR_FROM_DOMAIN
1405     | VIR_FROM_UML
1406     | VIR_FROM_NODEDEV
1407     | VIR_FROM_XEN_INOTIFY
1408     | VIR_FROM_SECURITY
1409     | VIR_FROM_VBOX
1410     | VIR_FROM_INTERFACE
1411     | VIR_FROM_ONE
1412     | VIR_FROM_ESX
1413     | VIR_FROM_PHYP
1414     | VIR_FROM_SECRET
1415     | VIR_FROM_CPU
1416     | VIR_FROM_XENAPI
1417     | VIR_FROM_NWFILTER
1418     | VIR_FROM_HOOK
1419     | VIR_FROM_DOMAIN_SNAPSHOT
1420     | VIR_FROM_AUDIT
1421     | VIR_FROM_SYSINFO
1422     | VIR_FROM_STREAMS
1423     | VIR_FROM_VMWARE
1424     | VIR_FROM_EVENT
1425     | VIR_FROM_LIBXL
1426     | VIR_FROM_LOCKING
1427     | VIR_FROM_HYPERV
1428     | VIR_FROM_CAPABILITIES
1429     | VIR_FROM_URI
1430     | VIR_FROM_AUTH
1431     | VIR_FROM_DBUS
1432     | VIR_FROM_PARALLELS
1433     | VIR_FROM_DEVICE
1434     | VIR_FROM_SSH
1435     | VIR_FROM_LOCKSPACE
1436     | VIR_FROM_INITCTL
1437     | VIR_FROM_IDENTITY
1438     | VIR_FROM_CGROUP
1439     | VIR_FROM_ACCESS
1440     | VIR_FROM_SYSTEMD
1441     | VIR_FROM_BHYVE
1442     | VIR_FROM_CRYPTO
1443     | VIR_FROM_FIREWALL
1444     | VIR_FROM_POLKIT
1445     | VIR_FROM_THREAD
1446     | VIR_FROM_ADMIN
1447     | VIR_FROM_LOGGING
1448     | VIR_FROM_XENXL
1449     | VIR_FROM_PERF
1450     | VIR_FROM_LIBSSH
1451     | VIR_FROM_RESCTRL
1452         (* ^^ NB: If you add a variant you MUST edit
1453            libvirt_c_epilogue.c: MAX_VIR_* *)
1454     | VIR_FROM_UNKNOWN of int
1455         (** Subsystem / driver which produced the error. *)
1456
1457   val string_of_domain : domain -> string
1458
1459   type level =
1460     | VIR_ERR_NONE
1461     | VIR_ERR_WARNING
1462     | VIR_ERR_ERROR
1463         (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *)
1464     | VIR_ERR_UNKNOWN_LEVEL of int
1465         (** No error, a warning or an error. *)
1466
1467   val string_of_level : level -> string
1468
1469   type t = {
1470     code : code;                        (** Error code. *)
1471     domain : domain;                    (** Origin of the error. *)
1472     message : string option;            (** Human-readable message. *)
1473     level : level;                      (** Error or warning. *)
1474     str1 : string option;               (** Informational string. *)
1475     str2 : string option;               (** Informational string. *)
1476     str3 : string option;               (** Informational string. *)
1477     int1 : int32;                       (** Informational integer. *)
1478     int2 : int32;                       (** Informational integer. *)
1479   }
1480     (** An error object. *)
1481
1482   val to_string : t -> string
1483     (** Turn the exception into a printable string. *)
1484
1485   val get_last_error : unit -> t option
1486   val get_last_conn_error : [>`R] Connect.t -> t option
1487     (** Get the last error at a global or connection level.
1488
1489         Normally you do not need to use these functions because
1490         the library automatically turns errors into exceptions.
1491     *)
1492
1493   val reset_last_error : unit -> unit
1494   val reset_last_conn_error : [>`R] Connect.t -> unit
1495     (** Reset the error at a global or connection level.
1496
1497         Normally you do not need to use these functions.
1498     *)
1499
1500   val no_error : unit -> t
1501     (** Creates an empty error message.
1502
1503         Normally you do not need to use this function.
1504     *)
1505 end
1506   (** Module dealing with errors. *)
1507
1508 exception Virterror of Virterror.t
1509 (** This exception can be raised by any library function that detects
1510     an error.  To get a printable error message, call
1511     {!Virterror.to_string} on the content of this exception.
1512 *)
1513
1514 exception Not_supported of string
1515 (**
1516     Functions may raise
1517     [Not_supported "virFoo"]
1518     (where [virFoo] is the libvirt function name) if a function is
1519     not supported at either compile or run time.  This applies to
1520     any libvirt function added after version 0.2.1.
1521
1522     See also {{:http://libvirt.org/hvsupport.html}http://libvirt.org/hvsupport.html}
1523 *)
1524
1525 (** {3 Utility functions} *)
1526
1527 val map_ignore_errors : ('a -> 'b) -> 'a list -> 'b list
1528 (** [map_ignore_errors f xs] calls function [f] for each element of [xs].
1529
1530     This is just like [List.map] except that if [f x] throws a
1531     {!Virterror.t} exception, the error is ignored and [f x]
1532     is not returned in the final list.
1533
1534     This function is primarily useful when dealing with domains which
1535     might 'disappear' asynchronously from the currently running
1536     program.
1537 *)