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   val connect : ?name:string -> unit -> rw t
 264   val connect_readonly : ?name:string -> unit -> ro t
 265     (** [connect ~name ()] connects to the hypervisor with URI [name].
 266
 267         [connect ()] connects to the default hypervisor.
 268
 269         [connect_readonly] is the same but connects in read-only mode.
 270     *)
 271
 272   val close : [>`R] t -> unit
 273     (** [close conn] closes and frees the connection object in memory.
 274
 275         The connection is automatically closed if it is garbage
 276         collected.  This function just forces it to be closed
 277         and freed right away.
 278     *)
 279
 280   val get_type : [>`R] t -> string
 281     (** Returns the name of the driver (hypervisor). *)
 282
 283   val get_version : [>`R] t -> int
 284     (** Returns the driver version
 285         [major * 1_000_000 + minor * 1000 + release]
 286     *)
 287   val get_hostname : [>`R] t -> string
 288     (** Returns the hostname of the physical server. *)
 289   val get_uri : [>`R] t -> string
 290     (** Returns the canonical connection URI. *)
 291   val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
 292     (** Returns the maximum number of virtual CPUs
 293         supported by a guest VM of a particular type. *)
 294   val list_domains : [>`R] t -> int -> int array
 295     (** [list_domains conn max] returns the running domain IDs,
 296         up to a maximum of [max] entries.
 297
 298         Call {!num_of_domains} first to get a value for [max].
 299
 300         See also:
 301         {!Libvirt.Domain.get_domains},
 302         {!Libvirt.Domain.get_domains_and_infos}.
 303     *)
 304   val num_of_domains : [>`R] t -> int
 305     (** Returns the number of running domains. *)
 306   val get_capabilities : [>`R] t -> xml
 307     (** Returns the hypervisor capabilities (as XML). *)
 308   val num_of_defined_domains : [>`R] t -> int
 309     (** Returns the number of inactive (shutdown) domains. *)
 310   val list_defined_domains : [>`R] t -> int -> string array
 311     (** [list_defined_domains conn max]
 312         returns the names of the inactive domains, up to
 313         a maximum of [max] entries.
 314
 315         Call {!num_of_defined_domains} first to get a value for [max].
 316
 317         See also:
 318         {!Libvirt.Domain.get_domains},
 319         {!Libvirt.Domain.get_domains_and_infos}.
 320     *)
 321   val num_of_networks : [>`R] t -> int
 322     (** Returns the number of networks. *)
 323   val list_networks : [>`R] t -> int -> string array
 324     (** [list_networks conn max]
 325         returns the names of the networks, up to a maximum
 326         of [max] entries.
 327         Call {!num_of_networks} first to get a value for [max].
 328     *)
 329   val num_of_defined_networks : [>`R] t -> int
 330     (** Returns the number of inactive networks. *)
 331   val list_defined_networks : [>`R] t -> int -> string array
 332     (** [list_defined_networks conn max]
 333         returns the names of the inactive networks, up to a maximum
 334         of [max] entries.
 335         Call {!num_of_defined_networks} first to get a value for [max].
 336     *)
 337
 338   val num_of_pools : [>`R] t -> int
 339     (** Returns the number of storage pools. *)
 340   val list_pools : [>`R] t -> int -> string array
 341     (** Return list of storage pools. *)
 342   val num_of_defined_pools : [>`R] t -> int
 343     (** Returns the number of storage pools. *)
 344   val list_defined_pools : [>`R] t -> int -> string array
 345     (** Return list of storage pools. *)
 346
 347     (* The name of this function is inconsistent, but the inconsistency
 348      * is really in libvirt itself.
 349      *)
 350   val get_node_info : [>`R] t -> node_info
 351     (** Return information about the physical server. *)
 352
 353   val node_get_free_memory : [> `R] t -> int64
 354     (**
 355        [node_get_free_memory conn]
 356        returns the amount of free memory (not allocated to any guest)
 357        in the machine.
 358     *)
 359
 360   val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array
 361     (**
 362        [node_get_cells_free_memory conn start max]
 363        returns the amount of free memory on each NUMA cell in kilobytes.
 364        [start] is the first cell for which we return free memory.
 365        [max] is the maximum number of cells for which we return free memory.
 366        Returns an array of up to [max] entries in length.
 367     *)
 368
 369   val maxcpus_of_node_info : node_info -> int
 370     (** Calculate the total number of CPUs supported (but not necessarily
 371         active) in the host.
 372     *)
 373
 374   val cpumaplen : int -> int
 375     (** Calculate the length (in bytes) required to store the complete
 376         CPU map between a single virtual and all physical CPUs of a domain.
 377     *)
 378
 379   val use_cpu : bytes -> int -> unit
 380     (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
 381   val unuse_cpu : bytes -> int -> unit
 382     (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
 383   val cpu_usable : bytes -> int -> int -> int -> bool
 384     (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
 385         [cpu] is usable by [vcpu]. *)
 386
 387   val set_keep_alive : [>`R] t -> int -> int -> unit
 388     (** [set_keep_alive conn interval count] starts sending keepalive
 389         messages after [interval] seconds of inactivity and consider the
 390         connection to be broken when no response is received after [count]
 391         keepalive messages.
 392         Note: the client has to implement and run an event loop to
 393         be able to use keep-alive messages. *)
 394
 395   external const : [>`R] t -> ro t = "%identity"
 396     (** [const conn] turns a read/write connection into a read-only
 397         connection.  Note that the opposite operation is impossible.
 398       *)
 399 end
 400   (** Module dealing with connections.  [Connect.t] is the
 401       connection object. *)
 402
 403 (** {3 Domains} *)
 404
 405 module Domain :
 406 sig
 407   type 'rw t
 408     (** Domain handle.  Read-only handles have type [ro Domain.t] and
 409         read-write handles have type [rw Domain.t].
 410     *)
 411
 412   type state =
 413     | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
 414     | InfoShutdown | InfoShutoff | InfoCrashed
 415
 416   type info = {
 417     state : state;                      (** running state *)
 418     max_mem : int64;                    (** maximum memory in kilobytes *)
 419     memory : int64;                     (** memory used in kilobytes *)
 420     nr_virt_cpu : int;                  (** number of virtual CPUs *)
 421     cpu_time : int64;                   (** CPU time used in nanoseconds *)
 422   }
 423
 424   type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
 425
 426   type vcpu_info = {
 427     number : int;                       (** virtual CPU number *)
 428     vcpu_state : vcpu_state;            (** state *)
 429     vcpu_time : int64;                  (** CPU time used in nanoseconds *)
 430     cpu : int;                          (** real CPU number, -1 if offline *)
 431   }
 432
 433   type domain_create_flag =
 434   | START_PAUSED                        (** Launch guest in paused state *)
 435   | START_AUTODESTROY                   (** Automatically kill guest on close *)
 436   | START_BYPASS_CACHE                  (** Avoid filesystem cache pollution *)
 437   | START_FORCE_BOOT                    (** Discard any managed save *)
 438   | START_VALIDATE                      (** Validate XML against schema *)
 439
 440   type sched_param = string * sched_param_value
 441   and sched_param_value =
 442     | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
 443     | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
 444     | SchedFieldFloat of float | SchedFieldBool of bool
 445
 446   type typed_param = string * typed_param_value
 447   and typed_param_value =
 448     | TypedFieldInt32 of int32 | TypedFieldUInt32 of int32
 449     | TypedFieldInt64 of int64 | TypedFieldUInt64 of int64
 450     | TypedFieldFloat of float | TypedFieldBool of bool
 451     | TypedFieldString of string
 452
 453   type migrate_flag = Live
 454
 455   type memory_flag = Virtual
 456
 457   type list_flag =
 458     | ListActive
 459     | ListInactive
 460     | ListAll
 461
 462   type block_stats = {
 463     rd_req : int64;
 464     rd_bytes : int64;
 465     wr_req : int64;
 466     wr_bytes : int64;
 467     errs : int64;
 468   }
 469
 470   type interface_stats = {
 471     rx_bytes : int64;
 472     rx_packets : int64;
 473     rx_errs : int64;
 474     rx_drop : int64;
 475     tx_bytes : int64;
 476     tx_packets : int64;
 477     tx_errs : int64;
 478     tx_drop : int64;
 479   }
 480
 481   type get_all_domain_stats_flag =
 482     | GetAllDomainsStatsActive
 483     | GetAllDomainsStatsInactive
 484     | GetAllDomainsStatsOther
 485     | GetAllDomainsStatsPaused
 486     | GetAllDomainsStatsPersistent
 487     | GetAllDomainsStatsRunning
 488     | GetAllDomainsStatsShutoff
 489     | GetAllDomainsStatsTransient
 490     | GetAllDomainsStatsBacking
 491     | GetAllDomainsStatsEnforceStats
 492
 493   type stats_type =
 494     | StatsState | StatsCpuTotal | StatsBalloon | StatsVcpu
 495     | StatsInterface | StatsBlock | StatsPerf
 496
 497   type domain_stats_record = {
 498     dom_uuid : uuid;
 499     params : typed_param array;
 500   }
 501
 502   val max_peek : [>`R] t -> int
 503     (** Maximum size supported by the {!block_peek} and {!memory_peek}
 504         functions.  If you want to peek more than this then you must
 505         break your request into chunks. *)
 506
 507   val create_linux : [>`W] Connect.t -> xml -> rw t
 508     (** Create a new guest domain (not necessarily a Linux one)
 509         from the given XML.  Use {!create_xml} instead.
 510     *)
 511   val create_xml : [>`W] Connect.t -> xml -> domain_create_flag list -> rw t
 512     (** Create a new guest domain from the given XML. *)
 513   val lookup_by_id : 'a Connect.t -> int -> 'a t
 514     (** Lookup a domain by ID. *)
 515   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
 516     (** Lookup a domain by UUID.  This uses the packed byte array UUID. *)
 517   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
 518     (** Lookup a domain by (string) UUID. *)
 519   val lookup_by_name : 'a Connect.t -> string -> 'a t
 520     (** Lookup a domain by name. *)
 521   val destroy : [>`W] t -> unit
 522     (** Abruptly destroy a domain. *)
 523   val free : [>`R] t -> unit
 524     (** [free domain] frees the domain object in memory.
 525
 526         The domain object is automatically freed if it is garbage
 527         collected.  This function just forces it to be freed right
 528         away.
 529     *)
 530
 531   val suspend : [>`W] t -> unit
 532     (** Suspend a domain. *)
 533   val resume : [>`W] t -> unit
 534     (** Resume a domain. *)
 535   val save : [>`W] t -> filename -> unit
 536     (** Suspend a domain, then save it to the file. *)
 537   val restore : [>`W] Connect.t -> filename -> unit
 538     (** Restore a domain from a file. *)
 539   val core_dump : [>`W] t -> filename -> unit
 540     (** Force a domain to core dump to the named file. *)
 541   val shutdown : [>`W] t -> unit
 542     (** Shutdown a domain. *)
 543   val reboot : [>`W] t -> unit
 544     (** Reboot a domain. *)
 545   val get_name : [>`R] t -> string
 546     (** Get the domain name. *)
 547   val get_uuid : [>`R] t -> uuid
 548     (** Get the domain UUID (as a packed byte array). *)
 549   val get_uuid_string : [>`R] t -> string
 550     (** Get the domain UUID (as a printable string). *)
 551   val get_id : [>`R] t -> int
 552     (** [get_id dom] returns the ID of the domain.  In most cases
 553         this returns [-1] if the domain is not running. *)
 554   val get_os_type : [>`R] t -> string
 555     (** Get the operating system type. *)
 556   val get_max_memory : [>`R] t -> int64
 557     (** Get the maximum memory allocation. *)
 558   val set_max_memory : [>`W] t -> int64 -> unit
 559     (** Set the maximum memory allocation. *)
 560   val set_memory : [>`W] t -> int64 -> unit
 561     (** Set the normal memory allocation. *)
 562   val get_info : [>`R] t -> info
 563     (** Get information about a domain. *)
 564   val get_xml_desc : [>`R] t -> xml
 565     (** Get the XML description of a domain. *)
 566   val get_scheduler_type : [>`R] t -> string * int
 567     (** Get the scheduler type. *)
 568   val get_scheduler_parameters : [>`R] t -> int -> sched_param array
 569     (** Get the array of scheduler parameters. *)
 570   val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
 571     (** Set the array of scheduler parameters. *)
 572   val define_xml : [>`W] Connect.t -> xml -> rw t
 573     (** Define a new domain (but don't start it up) from the XML. *)
 574   val undefine : [>`W] t -> unit
 575     (** Undefine a domain - removes its configuration. *)
 576   val create : [>`W] t -> unit
 577     (** Launch a defined (inactive) domain. *)
 578   val get_autostart : [>`R] t -> bool
 579     (** Get the autostart flag for a domain. *)
 580   val set_autostart : [>`W] t -> bool -> unit
 581     (** Set the autostart flag for a domain. *)
 582   val set_vcpus : [>`W] t -> int -> unit
 583     (** Change the number of vCPUs available to a domain. *)
 584   val pin_vcpu : [>`W] t -> int -> string -> unit
 585     (** [pin_vcpu dom vcpu bitmap] pins a domain vCPU to a bitmap of physical
 586         CPUs.  See the libvirt documentation for details of the
 587         layout of the bitmap. *)
 588   val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
 589     (** [get_vcpus dom maxinfo maplen] returns the pinning information
 590         for a domain.  See the libvirt documentation for details
 591         of the array and bitmap returned from this function.
 592     *)
 593   val get_cpu_stats : [>`R] t -> typed_param list array
 594     (** [get_pcpu_stats dom] returns the physical CPU stats
 595         for a domain.  See the libvirt documentation for details.
 596     *)
 597   val get_max_vcpus : [>`R] t -> int
 598     (** Returns the maximum number of vCPUs supported for this domain. *)
 599   val attach_device : [>`W] t -> xml -> unit
 600     (** Attach a device (described by the device XML) to a domain. *)
 601   val detach_device : [>`W] t -> xml -> unit
 602     (** Detach a device (described by the device XML) from a domain. *)
 603
 604   val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
 605     ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
 606     (** [migrate dom dconn flags ()] migrates a domain to a
 607         destination host described by [dconn].
 608
 609         The optional flag [?dname] is used to rename the domain.
 610
 611         The optional flag [?uri] is used to route the migration.
 612
 613         The optional flag [?bandwidth] is used to limit the bandwidth
 614         used for migration (in Mbps). *)
 615
 616   val block_stats : [>`R] t -> string -> block_stats
 617     (** Returns block device stats. *)
 618   val interface_stats : [>`R] t -> string -> interface_stats
 619     (** Returns network interface stats. *)
 620
 621   val block_peek : [>`W] t -> string -> int64 -> int -> string -> int -> unit
 622     (** [block_peek dom path offset size buf boff] reads [size] bytes at
 623         [offset] in the domain's [path] block device.
 624
 625         If successful then the data is written into [buf] starting
 626         at offset [boff], for [size] bytes.
 627
 628         See also {!max_peek}. *)
 629   val memory_peek : [>`W] t -> memory_flag list -> int64 -> int ->
 630     string -> int -> unit
 631     (** [memory_peek dom Virtual offset size] reads [size] bytes
 632         at [offset] in the domain's virtual memory.
 633
 634         If successful then the data is written into [buf] starting
 635         at offset [boff], for [size] bytes.
 636
 637         See also {!max_peek}. *)
 638
 639   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"
 640     (** [get_all_domain_stats conn stats flags] allows you to read
 641         all stats across multiple/all domains in a single call.
 642
 643         See the libvirt documentation for
 644         [virConnectGetAllDomainStats]. *)
 645
 646   external const : [>`R] t -> ro t = "%identity"
 647     (** [const dom] turns a read/write domain handle into a read-only
 648         domain handle.  Note that the opposite operation is impossible.
 649       *)
 650
 651   val get_domains : ([>`R] as 'a) Connect.t -> list_flag list -> 'a t list
 652     (** Get the active and/or inactive domains using the most
 653         efficient method available.
 654
 655         See also:
 656         {!get_domains_and_infos},
 657         {!Connect.list_domains},
 658         {!Connect.list_defined_domains}.
 659   *)
 660
 661   val get_domains_and_infos : ([>`R] as 'a) Connect.t -> list_flag list ->
 662     ('a t * info) list
 663     (** This gets the active and/or inactive domains and the
 664         domain info for each one using the most efficient
 665         method available.
 666
 667         See also:
 668         {!get_domains},
 669         {!Connect.list_domains},
 670         {!Connect.list_defined_domains},
 671         {!get_info}.
 672     *)
 673
 674 end
 675   (** Module dealing with domains.  [Domain.t] is the
 676       domain object. *)
 677
 678 module Event :
 679 sig
 680
 681   module Defined : sig
 682     type t = [
 683       | `Added          (** Newly created config file *)
 684       | `Updated        (** Changed config file *)
 685       | `Unknown of int
 686     ]
 687
 688     val to_string: t -> string
 689   end
 690
 691   module Undefined : sig
 692     type t = [
 693       | `Removed        (** Deleted the config file *)
 694       | `Unknown of int
 695     ]
 696
 697     val to_string: t -> string
 698   end
 699
 700   module Started : sig
 701     type t = [
 702       | `Booted         (** Normal startup from boot *)
 703       | `Migrated       (** Incoming migration from another host *)
 704       | `Restored       (** Restored from a state file *)
 705       | `FromSnapshot   (** Restored from snapshot *)
 706       | `Wakeup         (** Started due to wakeup event *)
 707       | `Unknown of int
 708     ]
 709
 710     val to_string: t -> string
 711   end
 712
 713   module Suspended : sig
 714     type t = [
 715       | `Paused        (** Normal suspend due to admin pause *)
 716       | `Migrated      (** Suspended for offline migration *)
 717       | `IOError       (** Suspended due to a disk I/O error *)
 718       | `Watchdog      (** Suspended due to a watchdog firing *)
 719       | `Restored      (** Restored from paused state file *)
 720       | `FromSnapshot  (** Restored from paused snapshot *)
 721       | `APIError      (** suspended after failure during libvirt API call *)
 722       | `Unknown of int
 723     ]
 724
 725     val to_string: t -> string
 726   end
 727
 728   module Resumed : sig
 729     type t = [
 730       | `Unpaused      (** Normal resume due to admin unpause *)
 731       | `Migrated      (** Resumed for completion of migration *)
 732       | `FromSnapshot  (** Resumed from snapshot *)
 733       | `Unknown of int
 734     ]
 735
 736     val to_string: t -> string
 737   end
 738
 739   module Stopped : sig
 740     type t = [
 741       | `Shutdown     (** Normal shutdown *)
 742       | `Destroyed    (** Forced poweroff from host *)
 743       | `Crashed      (** Guest crashed *)
 744       | `Migrated     (** Migrated off to another host *)
 745       | `Saved        (** Saved to a state file *)
 746       | `Failed       (** Host emulator/mgmt failed *)
 747       | `FromSnapshot (** offline snapshot loaded *)
 748       | `Unknown of int
 749     ]
 750
 751     val to_string: t -> string
 752   end
 753
 754   module PM_suspended : sig
 755     type t = [
 756       | `Memory       (** Guest was PM suspended to memory *)
 757       | `Disk         (** Guest was PM suspended to disk *)
 758       | `Unknown of int
 759     ]
 760
 761     val to_string: t -> string
 762   end
 763
 764   module Lifecycle : sig
 765     type t = [
 766       | `Defined of Defined.t
 767       | `Undefined of Undefined.t
 768       | `Started of Started.t
 769       | `Suspended of Suspended.t
 770       | `Resumed of Resumed.t
 771       | `Stopped of Stopped.t
 772       | `Shutdown (* no detail defined yet *)
 773       | `PMSuspended of PM_suspended.t
 774       | `Unknown of int
 775     ]
 776
 777     val to_string: t -> string
 778   end
 779
 780   module Reboot : sig
 781     type t = unit
 782
 783     val to_string: t -> string
 784   end
 785
 786   module Rtc_change : sig
 787     type t = int64
 788
 789     val to_string: t -> string
 790   end
 791
 792   module Watchdog : sig
 793     type t = [
 794       | `None           (** No action, watchdog ignored *)
 795       | `Pause          (** Guest CPUs are paused *)
 796       | `Reset          (** Guest CPUs are reset *)
 797       | `Poweroff       (** Guest is forcably powered off *)
 798       | `Shutdown       (** Guest is requested to gracefully shutdown *)
 799       | `Debug          (** No action, a debug message logged *)
 800       | `Unknown of int (** newer libvirt *)
 801     ]
 802
 803     val to_string: t -> string
 804   end
 805
 806   module Io_error : sig
 807     (** Represents both IOError and IOErrorReason *)
 808     type action = [
 809       | `None           (** No action, IO error ignored *)
 810       | `Pause          (** Guest CPUs are paused *)
 811       | `Report         (** IO error reported to guest OS *)
 812       | `Unknown of int (** newer libvirt *)
 813     ]
 814
 815     type t = {
 816       src_path: string option;  (** The host file on which the I/O error occurred *)
 817       dev_alias: string option; (** The guest device alias associated with the path *)
 818       action: action;    (** The action that is to be taken due to the IO error *)
 819       reason: string option;    (** The cause of the IO error *)
 820     }
 821
 822     val to_string: t -> string
 823   end
 824
 825   module Graphics_address : sig
 826     type family = [
 827       | `Ipv4           (** IPv4 address *)
 828       | `Ipv6           (** IPv6 address *)
 829       | `Unix           (** UNIX socket path *)
 830       | `Unknown of int (** newer libvirt *)
 831     ]
 832
 833     type t = {
 834       family: family;         (** Address family *)
 835       node: string option;    (** Address of node (eg IP address, or UNIX path *)
 836       service: string option; (** Service name/number (eg TCP port, or NULL) *)
 837     }
 838
 839     val to_string: t -> string
 840   end
 841
 842   module Graphics_subject : sig
 843     type identity = {
 844       ty: string option;   (** Type of identity *)
 845       name: string option; (** Identity value *)
 846     }
 847
 848     type t = identity list
 849
 850     val to_string: t -> string
 851   end
 852
 853   module Graphics : sig
 854     type phase = [
 855       | `Connect        (** Initial socket connection established *)
 856       | `Initialize     (** Authentication & setup completed *)
 857       | `Disconnect     (** Final socket disconnection *)
 858       | `Unknown of int (** newer libvirt *)
 859     ]
 860
 861     type t = {
 862       phase: phase;                (** the phase of the connection *)
 863       local: Graphics_address.t;   (** the local server address *)
 864       remote: Graphics_address.t;  (** the remote client address *)
 865       auth_scheme: string option;  (** the authentication scheme activated *)
 866       subject: Graphics_subject.t; (** the authenticated subject (user) *)
 867     }
 868
 869     val to_string: t -> string
 870   end
 871
 872   module Control_error : sig
 873     type t = unit
 874
 875     val to_string: t -> string
 876   end
 877
 878   module Block_job : sig
 879     type ty = [
 880       | `KnownUnknown (** explicitly named UNKNOWN in the spec *)
 881       | `Pull
 882       | `Copy
 883       | `Commit
 884       | `Unknown of int
 885     ]
 886
 887     type status = [
 888       | `Completed
 889       | `Failed
 890       | `Cancelled
 891       | `Ready
 892       | `Unknown of int
 893     ]
 894
 895     type t = {
 896       disk: string option; (** fully-qualified name of the affected disk *)
 897       ty: ty;              (** type of block job *)
 898       status: status;      (** final status of the operation *)
 899     }
 900
 901     val to_string: t -> string
 902   end
 903
 904   module Disk_change : sig
 905     type reason = [
 906       | `MissingOnStart
 907       | `Unknown of int
 908     ]
 909
 910     type t = {
 911       old_src_path: string option; (** old source path *)
 912       new_src_path: string option; (** new source path *)
 913       dev_alias: string option;    (** device alias name *)
 914       reason: reason;              (** reason why this callback was called *)
 915     }
 916
 917     val to_string: t -> string
 918   end
 919
 920   module Tray_change : sig
 921     type reason = [
 922       | `Open
 923       | `Close
 924       | `Unknown of int
 925     ]
 926
 927     type t = {
 928       dev_alias: string option; (** device alias *)
 929       reason: reason;           (** why the tray status was changed *)
 930     }
 931
 932     val to_string: t -> string
 933   end
 934
 935   module PM_wakeup : sig
 936     type reason = [
 937       | `Unknown of int
 938     ]
 939
 940     type t = reason
 941
 942     val to_string: t -> string
 943   end
 944
 945   module PM_suspend : sig
 946     type reason = [
 947       | `Unknown of int
 948     ]
 949
 950     type t = reason
 951
 952     val to_string: t -> string
 953   end
 954
 955   module Balloon_change : sig
 956     type t = int64
 957
 958     val to_string: t -> string
 959   end
 960
 961   module PM_suspend_disk : sig
 962     type reason = [
 963       | `Unknown of int
 964     ]
 965
 966     type t = reason
 967
 968     val to_string: t -> string
 969   end
 970
 971
 972   type callback =
 973     | Lifecycle     of ([`R] Domain.t -> Lifecycle.t -> unit)
 974     | Reboot        of ([`R] Domain.t -> Reboot.t -> unit)
 975     | RtcChange     of ([`R] Domain.t -> Rtc_change.t -> unit)
 976     | Watchdog      of ([`R] Domain.t -> Watchdog.t -> unit)
 977     | IOError       of ([`R] Domain.t -> Io_error.t -> unit)
 978     | Graphics      of ([`R] Domain.t -> Graphics.t -> unit)
 979     | IOErrorReason of ([`R] Domain.t -> Io_error.t -> unit)
 980     | ControlError  of ([`R] Domain.t -> Control_error.t -> unit)
 981     | BlockJob      of ([`R] Domain.t -> Block_job.t -> unit)
 982     | DiskChange    of ([`R] Domain.t -> Disk_change.t -> unit)
 983     | TrayChange    of ([`R] Domain.t -> Tray_change.t -> unit)
 984     | PMWakeUp      of ([`R] Domain.t -> PM_wakeup.t -> unit)
 985     | PMSuspend     of ([`R] Domain.t -> PM_suspend.t -> unit)
 986     | BalloonChange of ([`R] Domain.t -> Balloon_change.t -> unit)
 987     | PMSuspendDisk of ([`R] Domain.t -> PM_suspend_disk.t -> unit)
 988
 989     (** type of a registered call back function *)
 990
 991   val register_default_impl : unit -> unit
 992     (** Registers the default event loop based on poll(). This
 993         must be done before connections are opened.
 994
 995         Once registered call run_default_impl in a loop. *)
 996
 997   val run_default_impl : unit -> unit
 998     (** Runs one iteration of the event loop. Applications will
 999         generally want to have a thread which invokes this in an
1000         infinite loop. *)
1001
1002   type callback_id
1003     (** an individual event registration *)
1004
1005   val register_any : 'a Connect.t -> ?dom:'a Domain.t -> callback -> callback_id
1006     (** [register_any con ?dom callback] registers [callback]
1007         to receive notification of arbitrary domain events. Return
1008         a registration id which can be used in [deregister_any].
1009
1010         If [?dom] is None then register for this kind of event on
1011         all domains. If [dom] is [Some d] then register for this
1012         kind of event only on [d].
1013     *)
1014
1015   val deregister_any : 'a Connect.t -> callback_id -> unit
1016     (** [deregister_any con id] deregisters the previously registered
1017         callback with id [id]. *)
1018
1019   type timer_id
1020     (** an individual timer event *)
1021
1022   val add_timeout : 'a Connect.t -> int -> (unit -> unit) -> timer_id
1023     (** [add_timeout con ms cb] registers [cb] as a timeout callback
1024         which will be called every [ms] milliseconds *)
1025
1026   val remove_timeout : 'a Connect.t -> timer_id -> unit
1027     (** [remove_timeout con t] deregisters timeout callback [t]. *)
1028
1029 end
1030   (** Module dealing with events generated by domain
1031       state changes. *)
1032
1033 (** {3 Networks} *)
1034
1035 module Network :
1036 sig
1037   type 'rw t
1038     (** Network handle.  Read-only handles have type [ro Network.t] and
1039         read-write handles have type [rw Network.t].
1040     *)
1041
1042   val lookup_by_name : 'a Connect.t -> string -> 'a t
1043     (** Lookup a network by name. *)
1044   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
1045     (** Lookup a network by (packed) UUID. *)
1046   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
1047     (** Lookup a network by UUID string. *)
1048   val create_xml : [>`W] Connect.t -> xml -> rw t
1049     (** Create a network. *)
1050   val define_xml : [>`W] Connect.t -> xml -> rw t
1051     (** Define but don't activate a network. *)
1052   val undefine : [>`W] t -> unit
1053     (** Undefine configuration of a network. *)
1054   val create : [>`W] t -> unit
1055     (** Start up a defined (inactive) network. *)
1056   val destroy : [>`W] t -> unit
1057     (** Destroy a network. *)
1058   val free : [>`R] t -> unit
1059     (** [free network] frees the network object in memory.
1060
1061         The network object is automatically freed if it is garbage
1062         collected.  This function just forces it to be freed right
1063         away.
1064     *)
1065
1066   val get_name : [>`R] t -> string
1067     (** Get network name. *)
1068   val get_uuid : [>`R] t -> uuid
1069     (** Get network packed UUID. *)
1070   val get_uuid_string : [>`R] t -> string
1071     (** Get network UUID as a printable string. *)
1072   val get_xml_desc : [>`R] t -> xml
1073     (** Get XML description of a network. *)
1074   val get_bridge_name : [>`R] t -> string
1075     (** Get bridge device name of a network. *)
1076   val get_autostart : [>`R] t -> bool
1077     (** Get the autostart flag for a network. *)
1078   val set_autostart : [>`W] t -> bool -> unit
1079     (** Set the autostart flag for a network. *)
1080
1081   external const : [>`R] t -> ro t = "%identity"
1082     (** [const network] turns a read/write network handle into a read-only
1083         network handle.  Note that the opposite operation is impossible.
1084       *)
1085 end
1086   (** Module dealing with networks.  [Network.t] is the
1087       network object. *)
1088
1089 (** {3 Storage pools} *)
1090
1091 module Pool :
1092 sig
1093   type 'rw t
1094     (** Storage pool handle. *)
1095
1096   type pool_state = Inactive | Building | Running | Degraded
1097     (** State of the storage pool. *)
1098
1099   type pool_build_flags = New | Repair | Resize
1100     (** Flags for creating a storage pool. *)
1101
1102   type pool_delete_flags = Normal | Zeroed
1103     (** Flags for deleting a storage pool. *)
1104
1105   type pool_info = {
1106     state : pool_state;                 (** Pool state. *)
1107     capacity : int64;                   (** Logical size in bytes. *)
1108     allocation : int64;                 (** Currently allocated in bytes. *)
1109     available : int64;                  (** Remaining free space bytes. *)
1110   }
1111
1112   val lookup_by_name : 'a Connect.t -> string -> 'a t
1113   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
1114   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
1115     (** Look up a storage pool by name, UUID or UUID string. *)
1116
1117   val create_xml : [>`W] Connect.t -> xml -> rw t
1118     (** Create a storage pool. *)
1119   val define_xml : [>`W] Connect.t -> xml -> rw t
1120     (** Define but don't activate a storage pool. *)
1121   val build : [>`W] t -> pool_build_flags -> unit
1122     (** Build a storage pool. *)
1123   val undefine : [>`W] t -> unit
1124     (** Undefine configuration of a storage pool. *)
1125   val create : [>`W] t -> unit
1126     (** Start up a defined (inactive) storage pool. *)
1127   val destroy : [>`W] t -> unit
1128     (** Destroy a storage pool. *)
1129   val delete : [>`W] t -> unit
1130     (** Delete a storage pool. *)
1131   val free : [>`R] t -> unit
1132     (** Free a storage pool object in memory.
1133
1134         The storage pool object is automatically freed if it is garbage
1135         collected.  This function just forces it to be freed right
1136         away.
1137     *)
1138   val refresh : [`R] t -> unit
1139     (** Refresh the list of volumes in the storage pool. *)
1140
1141   val get_name : [`R] t -> string
1142     (** Name of the pool. *)
1143   val get_uuid : [`R] t -> uuid
1144     (** Get the UUID (as a packed byte array). *)
1145   val get_uuid_string : [`R] t -> string
1146     (** Get the UUID (as a printable string). *)
1147   val get_info : [`R] t -> pool_info
1148     (** Get information about the pool. *)
1149   val get_xml_desc : [`R] t -> xml
1150     (** Get the XML description. *)
1151   val get_autostart : [`R] t -> bool
1152     (** Get the autostart flag for the storage pool. *)
1153   val set_autostart : [>`W] t -> bool -> unit
1154     (** Set the autostart flag for the storage pool. *)
1155
1156   val num_of_volumes : [`R] t -> int
1157     (** Returns the number of storage volumes within the storage pool. *)
1158   val list_volumes : [`R] t -> int -> string array
1159     (** Return list of storage volumes. *)
1160
1161   external const : [>`R] t -> ro t = "%identity"
1162     (** [const conn] turns a read/write storage pool into a read-only
1163         pool.  Note that the opposite operation is impossible.
1164       *)
1165 end
1166   (** Module dealing with storage pools. *)
1167
1168 (** {3 Storage volumes} *)
1169
1170 module Volume :
1171 sig
1172   type 'rw t
1173     (** Storage volume handle. *)
1174
1175   type vol_type = File | Block
1176     (** Type of a storage volume. *)
1177
1178   type vol_delete_flags = Normal | Zeroed
1179     (** Flags for deleting a storage volume. *)
1180
1181   type vol_info = {
1182     typ : vol_type;                     (** Type of storage volume. *)
1183     capacity : int64;                   (** Logical size in bytes. *)
1184     allocation : int64;                 (** Currently allocated in bytes. *)
1185   }
1186
1187   val lookup_by_name : 'a Pool.t -> string -> 'a t
1188   val lookup_by_key : 'a Connect.t -> string -> 'a t
1189   val lookup_by_path : 'a Connect.t -> string -> 'a t
1190     (** Look up a storage volume by name, key or path volume. *)
1191
1192   val pool_of_volume : 'a t -> 'a Pool.t
1193     (** Get the storage pool containing this volume. *)
1194
1195   val get_name : [`R] t -> string
1196     (** Name of the volume. *)
1197   val get_key : [`R] t -> string
1198     (** Key of the volume. *)
1199   val get_path : [`R] t -> string
1200     (** Path of the volume. *)
1201   val get_info : [`R] t -> vol_info
1202     (** Get information about the storage volume. *)
1203   val get_xml_desc : [`R] t -> xml
1204     (** Get the XML description. *)
1205
1206   val create_xml : [>`W] Pool.t -> xml -> unit
1207     (** Create a storage volume. *)
1208   val delete : [>`W] t -> vol_delete_flags -> unit
1209     (** Delete a storage volume. *)
1210   val free : [>`R] t -> unit
1211     (** Free a storage volume object in memory.
1212
1213         The storage volume object is automatically freed if it is garbage
1214         collected.  This function just forces it to be freed right
1215         away.
1216     *)
1217
1218   external const : [>`R] t -> ro t = "%identity"
1219     (** [const conn] turns a read/write storage volume into a read-only
1220         volume.  Note that the opposite operation is impossible.
1221       *)
1222 end
1223   (** Module dealing with storage volumes. *)
1224
1225 (** {3 Error handling and exceptions} *)
1226
1227 module Virterror :
1228 sig
1229   type code =
1230     | VIR_ERR_OK
1231     | VIR_ERR_INTERNAL_ERROR
1232     | VIR_ERR_NO_MEMORY
1233     | VIR_ERR_NO_SUPPORT
1234     | VIR_ERR_UNKNOWN_HOST
1235     | VIR_ERR_NO_CONNECT
1236     | VIR_ERR_INVALID_CONN
1237     | VIR_ERR_INVALID_DOMAIN
1238     | VIR_ERR_INVALID_ARG
1239     | VIR_ERR_OPERATION_FAILED
1240     | VIR_ERR_GET_FAILED
1241     | VIR_ERR_POST_FAILED
1242     | VIR_ERR_HTTP_ERROR
1243     | VIR_ERR_SEXPR_SERIAL
1244     | VIR_ERR_NO_XEN
1245     | VIR_ERR_XEN_CALL
1246     | VIR_ERR_OS_TYPE
1247     | VIR_ERR_NO_KERNEL
1248     | VIR_ERR_NO_ROOT
1249     | VIR_ERR_NO_SOURCE
1250     | VIR_ERR_NO_TARGET
1251     | VIR_ERR_NO_NAME
1252     | VIR_ERR_NO_OS
1253     | VIR_ERR_NO_DEVICE
1254     | VIR_ERR_NO_XENSTORE
1255     | VIR_ERR_DRIVER_FULL
1256     | VIR_ERR_CALL_FAILED
1257     | VIR_ERR_XML_ERROR
1258     | VIR_ERR_DOM_EXIST
1259     | VIR_ERR_OPERATION_DENIED
1260     | VIR_ERR_OPEN_FAILED
1261     | VIR_ERR_READ_FAILED
1262     | VIR_ERR_PARSE_FAILED
1263     | VIR_ERR_CONF_SYNTAX
1264     | VIR_ERR_WRITE_FAILED
1265     | VIR_ERR_XML_DETAIL
1266     | VIR_ERR_INVALID_NETWORK
1267     | VIR_ERR_NETWORK_EXIST
1268     | VIR_ERR_SYSTEM_ERROR
1269     | VIR_ERR_RPC
1270     | VIR_ERR_GNUTLS_ERROR
1271     | VIR_WAR_NO_NETWORK
1272     | VIR_ERR_NO_DOMAIN
1273     | VIR_ERR_NO_NETWORK
1274     | VIR_ERR_INVALID_MAC
1275     | VIR_ERR_AUTH_FAILED
1276     | VIR_ERR_INVALID_STORAGE_POOL
1277     | VIR_ERR_INVALID_STORAGE_VOL
1278     | VIR_WAR_NO_STORAGE
1279     | VIR_ERR_NO_STORAGE_POOL
1280     | VIR_ERR_NO_STORAGE_VOL
1281         (* ^^ NB: If you add a variant you MUST edit
1282            libvirt_c_epilogue.c:MAX_VIR_* *)
1283     | VIR_ERR_UNKNOWN of int
1284         (** See [<libvirt/virterror.h>] for meaning of these codes. *)
1285
1286   val string_of_code : code -> string
1287
1288   type domain =
1289     | VIR_FROM_NONE
1290     | VIR_FROM_XEN
1291     | VIR_FROM_XEND
1292     | VIR_FROM_XENSTORE
1293     | VIR_FROM_SEXPR
1294     | VIR_FROM_XML
1295     | VIR_FROM_DOM
1296     | VIR_FROM_RPC
1297     | VIR_FROM_PROXY
1298     | VIR_FROM_CONF
1299     | VIR_FROM_QEMU
1300     | VIR_FROM_NET
1301     | VIR_FROM_TEST
1302     | VIR_FROM_REMOTE
1303     | VIR_FROM_OPENVZ
1304     | VIR_FROM_XENXM
1305     | VIR_FROM_STATS_LINUX
1306     | VIR_FROM_STORAGE
1307         (* ^^ NB: If you add a variant you MUST edit
1308            libvirt_c_epilogue.c: MAX_VIR_* *)
1309     | VIR_FROM_UNKNOWN of int
1310         (** Subsystem / driver which produced the error. *)
1311
1312   val string_of_domain : domain -> string
1313
1314   type level =
1315     | VIR_ERR_NONE
1316     | VIR_ERR_WARNING
1317     | VIR_ERR_ERROR
1318         (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *)
1319     | VIR_ERR_UNKNOWN_LEVEL of int
1320         (** No error, a warning or an error. *)
1321
1322   val string_of_level : level -> string
1323
1324   type t = {
1325     code : code;                        (** Error code. *)
1326     domain : domain;                    (** Origin of the error. *)
1327     message : string option;            (** Human-readable message. *)
1328     level : level;                      (** Error or warning. *)
1329     str1 : string option;               (** Informational string. *)
1330     str2 : string option;               (** Informational string. *)
1331     str3 : string option;               (** Informational string. *)
1332     int1 : int32;                       (** Informational integer. *)
1333     int2 : int32;                       (** Informational integer. *)
1334   }
1335     (** An error object. *)
1336
1337   val to_string : t -> string
1338     (** Turn the exception into a printable string. *)
1339
1340   val get_last_error : unit -> t option
1341   val get_last_conn_error : [>`R] Connect.t -> t option
1342     (** Get the last error at a global or connection level.
1343
1344         Normally you do not need to use these functions because
1345         the library automatically turns errors into exceptions.
1346     *)
1347
1348   val reset_last_error : unit -> unit
1349   val reset_last_conn_error : [>`R] Connect.t -> unit
1350     (** Reset the error at a global or connection level.
1351
1352         Normally you do not need to use these functions.
1353     *)
1354
1355   val no_error : unit -> t
1356     (** Creates an empty error message.
1357
1358         Normally you do not need to use this function.
1359     *)
1360 end
1361   (** Module dealing with errors. *)
1362
1363 exception Virterror of Virterror.t
1364 (** This exception can be raised by any library function that detects
1365     an error.  To get a printable error message, call
1366     {!Virterror.to_string} on the content of this exception.
1367 *)
1368
1369 exception Not_supported of string
1370 (**
1371     Functions may raise
1372     [Not_supported "virFoo"]
1373     (where [virFoo] is the libvirt function name) if a function is
1374     not supported at either compile or run time.  This applies to
1375     any libvirt function added after version 0.2.1.
1376
1377     See also {{:http://libvirt.org/hvsupport.html}http://libvirt.org/hvsupport.html}
1378 *)
1379
1380 (** {3 Utility functions} *)
1381
1382 val map_ignore_errors : ('a -> 'b) -> 'a list -> 'b list
1383 (** [map_ignore_errors f xs] calls function [f] for each element of [xs].
1384
1385     This is just like [List.map] except that if [f x] throws a
1386     {!Virterror.t} exception, the error is ignored and [f x]
1387     is not returned in the final list.
1388
1389     This function is primarily useful when dealing with domains which
1390     might 'disappear' asynchronously from the currently running
1391     program.
1392 *)