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 : string -> int -> unit
 380     (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
 381   val unuse_cpu : string -> int -> unit
 382     (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
 383   val cpu_usable : string -> 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   val max_peek : [>`R] t -> int
 482     (** Maximum size supported by the {!block_peek} and {!memory_peek}
 483         functions.  If you want to peek more than this then you must
 484         break your request into chunks. *)
 485
 486   val create_linux : [>`W] Connect.t -> xml -> rw t
 487     (** Create a new guest domain (not necessarily a Linux one)
 488         from the given XML.  Use {!create_xml} instead.
 489     *)
 490   val create_xml : [>`W] Connect.t -> xml -> domain_create_flag list -> rw t
 491     (** Create a new guest domain from the given XML. *)
 492   val lookup_by_id : 'a Connect.t -> int -> 'a t
 493     (** Lookup a domain by ID. *)
 494   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
 495     (** Lookup a domain by UUID.  This uses the packed byte array UUID. *)
 496   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
 497     (** Lookup a domain by (string) UUID. *)
 498   val lookup_by_name : 'a Connect.t -> string -> 'a t
 499     (** Lookup a domain by name. *)
 500   val destroy : [>`W] t -> unit
 501     (** Abruptly destroy a domain. *)
 502   val free : [>`R] t -> unit
 503     (** [free domain] frees the domain object in memory.
 504
 505         The domain object is automatically freed if it is garbage
 506         collected.  This function just forces it to be freed right
 507         away.
 508     *)
 509
 510   val suspend : [>`W] t -> unit
 511     (** Suspend a domain. *)
 512   val resume : [>`W] t -> unit
 513     (** Resume a domain. *)
 514   val save : [>`W] t -> filename -> unit
 515     (** Suspend a domain, then save it to the file. *)
 516   val restore : [>`W] Connect.t -> filename -> unit
 517     (** Restore a domain from a file. *)
 518   val core_dump : [>`W] t -> filename -> unit
 519     (** Force a domain to core dump to the named file. *)
 520   val shutdown : [>`W] t -> unit
 521     (** Shutdown a domain. *)
 522   val reboot : [>`W] t -> unit
 523     (** Reboot a domain. *)
 524   val get_name : [>`R] t -> string
 525     (** Get the domain name. *)
 526   val get_uuid : [>`R] t -> uuid
 527     (** Get the domain UUID (as a packed byte array). *)
 528   val get_uuid_string : [>`R] t -> string
 529     (** Get the domain UUID (as a printable string). *)
 530   val get_id : [>`R] t -> int
 531     (** [get_id dom] returns the ID of the domain.  In most cases
 532         this returns [-1] if the domain is not running. *)
 533   val get_os_type : [>`R] t -> string
 534     (** Get the operating system type. *)
 535   val get_max_memory : [>`R] t -> int64
 536     (** Get the maximum memory allocation. *)
 537   val set_max_memory : [>`W] t -> int64 -> unit
 538     (** Set the maximum memory allocation. *)
 539   val set_memory : [>`W] t -> int64 -> unit
 540     (** Set the normal memory allocation. *)
 541   val get_info : [>`R] t -> info
 542     (** Get information about a domain. *)
 543   val get_xml_desc : [>`R] t -> xml
 544     (** Get the XML description of a domain. *)
 545   val get_scheduler_type : [>`R] t -> string * int
 546     (** Get the scheduler type. *)
 547   val get_scheduler_parameters : [>`R] t -> int -> sched_param array
 548     (** Get the array of scheduler parameters. *)
 549   val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
 550     (** Set the array of scheduler parameters. *)
 551   val define_xml : [>`W] Connect.t -> xml -> rw t
 552     (** Define a new domain (but don't start it up) from the XML. *)
 553   val undefine : [>`W] t -> unit
 554     (** Undefine a domain - removes its configuration. *)
 555   val create : [>`W] t -> unit
 556     (** Launch a defined (inactive) domain. *)
 557   val get_autostart : [>`R] t -> bool
 558     (** Get the autostart flag for a domain. *)
 559   val set_autostart : [>`W] t -> bool -> unit
 560     (** Set the autostart flag for a domain. *)
 561   val set_vcpus : [>`W] t -> int -> unit
 562     (** Change the number of vCPUs available to a domain. *)
 563   val pin_vcpu : [>`W] t -> int -> string -> unit
 564     (** [pin_vcpu dom vcpu bitmap] pins a domain vCPU to a bitmap of physical
 565         CPUs.  See the libvirt documentation for details of the
 566         layout of the bitmap. *)
 567   val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
 568     (** [get_vcpus dom maxinfo maplen] returns the pinning information
 569         for a domain.  See the libvirt documentation for details
 570         of the array and bitmap returned from this function.
 571     *)
 572   val get_cpu_stats : [>`R] t -> typed_param list array
 573     (** [get_pcpu_stats dom] returns the physical CPU stats
 574         for a domain.  See the libvirt documentation for details.
 575     *)
 576   val get_max_vcpus : [>`R] t -> int
 577     (** Returns the maximum number of vCPUs supported for this domain. *)
 578   val attach_device : [>`W] t -> xml -> unit
 579     (** Attach a device (described by the device XML) to a domain. *)
 580   val detach_device : [>`W] t -> xml -> unit
 581     (** Detach a device (described by the device XML) from a domain. *)
 582
 583   val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
 584     ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
 585     (** [migrate dom dconn flags ()] migrates a domain to a
 586         destination host described by [dconn].
 587
 588         The optional flag [?dname] is used to rename the domain.
 589
 590         The optional flag [?uri] is used to route the migration.
 591
 592         The optional flag [?bandwidth] is used to limit the bandwidth
 593         used for migration (in Mbps). *)
 594
 595   val block_stats : [>`R] t -> string -> block_stats
 596     (** Returns block device stats. *)
 597   val interface_stats : [>`R] t -> string -> interface_stats
 598     (** Returns network interface stats. *)
 599
 600   val block_peek : [>`W] t -> string -> int64 -> int -> string -> int -> unit
 601     (** [block_peek dom path offset size buf boff] reads [size] bytes at
 602         [offset] in the domain's [path] block device.
 603
 604         If successful then the data is written into [buf] starting
 605         at offset [boff], for [size] bytes.
 606
 607         See also {!max_peek}. *)
 608   val memory_peek : [>`W] t -> memory_flag list -> int64 -> int ->
 609     string -> int -> unit
 610     (** [memory_peek dom Virtual offset size] reads [size] bytes
 611         at [offset] in the domain's virtual memory.
 612
 613         If successful then the data is written into [buf] starting
 614         at offset [boff], for [size] bytes.
 615
 616         See also {!max_peek}. *)
 617
 618   external const : [>`R] t -> ro t = "%identity"
 619     (** [const dom] turns a read/write domain handle into a read-only
 620         domain handle.  Note that the opposite operation is impossible.
 621       *)
 622
 623   val get_domains : ([>`R] as 'a) Connect.t -> list_flag list -> 'a t list
 624     (** Get the active and/or inactive domains using the most
 625         efficient method available.
 626
 627         See also:
 628         {!get_domains_and_infos},
 629         {!Connect.list_domains},
 630         {!Connect.list_defined_domains}.
 631   *)
 632
 633   val get_domains_and_infos : ([>`R] as 'a) Connect.t -> list_flag list ->
 634     ('a t * info) list
 635     (** This gets the active and/or inactive domains and the
 636         domain info for each one using the most efficient
 637         method available.
 638
 639         See also:
 640         {!get_domains},
 641         {!Connect.list_domains},
 642         {!Connect.list_defined_domains},
 643         {!get_info}.
 644     *)
 645
 646 end
 647   (** Module dealing with domains.  [Domain.t] is the
 648       domain object. *)
 649
 650 module Event :
 651 sig
 652
 653   module Defined : sig
 654     type t = [
 655       | `Added          (** Newly created config file *)
 656       | `Updated        (** Changed config file *)
 657       | `Unknown of int
 658     ]
 659
 660     val to_string: t -> string
 661   end
 662
 663   module Undefined : sig
 664     type t = [
 665       | `Removed        (** Deleted the config file *)
 666       | `Unknown of int
 667     ]
 668
 669     val to_string: t -> string
 670   end
 671
 672   module Started : sig
 673     type t = [
 674       | `Booted         (** Normal startup from boot *)
 675       | `Migrated       (** Incoming migration from another host *)
 676       | `Restored       (** Restored from a state file *)
 677       | `FromSnapshot   (** Restored from snapshot *)
 678       | `Wakeup         (** Started due to wakeup event *)
 679       | `Unknown of int
 680     ]
 681
 682     val to_string: t -> string
 683   end
 684
 685   module Suspended : sig
 686     type t = [
 687       | `Paused        (** Normal suspend due to admin pause *)
 688       | `Migrated      (** Suspended for offline migration *)
 689       | `IOError       (** Suspended due to a disk I/O error *)
 690       | `Watchdog      (** Suspended due to a watchdog firing *)
 691       | `Restored      (** Restored from paused state file *)
 692       | `FromSnapshot  (** Restored from paused snapshot *)
 693       | `APIError      (** suspended after failure during libvirt API call *)
 694       | `Unknown of int
 695     ]
 696
 697     val to_string: t -> string
 698   end
 699
 700   module Resumed : sig
 701     type t = [
 702       | `Unpaused      (** Normal resume due to admin unpause *)
 703       | `Migrated      (** Resumed for completion of migration *)
 704       | `FromSnapshot  (** Resumed from snapshot *)
 705       | `Unknown of int
 706     ]
 707
 708     val to_string: t -> string
 709   end
 710
 711   module Stopped : sig
 712     type t = [
 713       | `Shutdown     (** Normal shutdown *)
 714       | `Destroyed    (** Forced poweroff from host *)
 715       | `Crashed      (** Guest crashed *)
 716       | `Migrated     (** Migrated off to another host *)
 717       | `Saved        (** Saved to a state file *)
 718       | `Failed       (** Host emulator/mgmt failed *)
 719       | `FromSnapshot (** offline snapshot loaded *)
 720       | `Unknown of int
 721     ]
 722
 723     val to_string: t -> string
 724   end
 725
 726   module PM_suspended : sig
 727     type t = [
 728       | `Memory       (** Guest was PM suspended to memory *)
 729       | `Disk         (** Guest was PM suspended to disk *)
 730       | `Unknown of int
 731     ]
 732
 733     val to_string: t -> string
 734   end
 735
 736   module Lifecycle : sig
 737     type t = [
 738       | `Defined of Defined.t
 739       | `Undefined of Undefined.t
 740       | `Started of Started.t
 741       | `Suspended of Suspended.t
 742       | `Resumed of Resumed.t
 743       | `Stopped of Stopped.t
 744       | `Shutdown (* no detail defined yet *)
 745       | `PMSuspended of PM_suspended.t
 746       | `Unknown of int
 747     ]
 748
 749     val to_string: t -> string
 750   end
 751
 752   module Reboot : sig
 753     type t = unit
 754
 755     val to_string: t -> string
 756   end
 757
 758   module Rtc_change : sig
 759     type t = int64
 760
 761     val to_string: t -> string
 762   end
 763
 764   module Watchdog : sig
 765     type t = [
 766       | `None           (** No action, watchdog ignored *)
 767       | `Pause          (** Guest CPUs are paused *)
 768       | `Reset          (** Guest CPUs are reset *)
 769       | `Poweroff       (** Guest is forcably powered off *)
 770       | `Shutdown       (** Guest is requested to gracefully shutdown *)
 771       | `Debug          (** No action, a debug message logged *)
 772       | `Unknown of int (** newer libvirt *)
 773     ]
 774
 775     val to_string: t -> string
 776   end
 777
 778   module Io_error : sig
 779     (** Represents both IOError and IOErrorReason *)
 780     type action = [
 781       | `None           (** No action, IO error ignored *)
 782       | `Pause          (** Guest CPUs are paused *)
 783       | `Report         (** IO error reported to guest OS *)
 784       | `Unknown of int (** newer libvirt *)
 785     ]
 786
 787     type t = {
 788       src_path: string option;  (** The host file on which the I/O error occurred *)
 789       dev_alias: string option; (** The guest device alias associated with the path *)
 790       action: action;    (** The action that is to be taken due to the IO error *)
 791       reason: string option;    (** The cause of the IO error *)
 792     }
 793
 794     val to_string: t -> string
 795   end
 796
 797   module Graphics_address : sig
 798     type family = [
 799       | `Ipv4           (** IPv4 address *)
 800       | `Ipv6           (** IPv6 address *)
 801       | `Unix           (** UNIX socket path *)
 802       | `Unknown of int (** newer libvirt *)
 803     ]
 804
 805     type t = {
 806       family: family;         (** Address family *)
 807       node: string option;    (** Address of node (eg IP address, or UNIX path *)
 808       service: string option; (** Service name/number (eg TCP port, or NULL) *)
 809     }
 810
 811     val to_string: t -> string
 812   end
 813
 814   module Graphics_subject : sig
 815     type identity = {
 816       ty: string option;   (** Type of identity *)
 817       name: string option; (** Identity value *)
 818     }
 819
 820     type t = identity list
 821
 822     val to_string: t -> string
 823   end
 824
 825   module Graphics : sig
 826     type phase = [
 827       | `Connect        (** Initial socket connection established *)
 828       | `Initialize     (** Authentication & setup completed *)
 829       | `Disconnect     (** Final socket disconnection *)
 830       | `Unknown of int (** newer libvirt *)
 831     ]
 832
 833     type t = {
 834       phase: phase;                (** the phase of the connection *)
 835       local: Graphics_address.t;   (** the local server address *)
 836       remote: Graphics_address.t;  (** the remote client address *)
 837       auth_scheme: string option;  (** the authentication scheme activated *)
 838       subject: Graphics_subject.t; (** the authenticated subject (user) *)
 839     }
 840
 841     val to_string: t -> string
 842   end
 843
 844   module Control_error : sig
 845     type t = unit
 846
 847     val to_string: t -> string
 848   end
 849
 850   module Block_job : sig
 851     type ty = [
 852       | `KnownUnknown (** explicitly named UNKNOWN in the spec *)
 853       | `Pull
 854       | `Copy
 855       | `Commit
 856       | `Unknown of int
 857     ]
 858
 859     type status = [
 860       | `Completed
 861       | `Failed
 862       | `Cancelled
 863       | `Ready
 864       | `Unknown of int
 865     ]
 866
 867     type t = {
 868       disk: string option; (** fully-qualified name of the affected disk *)
 869       ty: ty;              (** type of block job *)
 870       status: status;      (** final status of the operation *)
 871     }
 872
 873     val to_string: t -> string
 874   end
 875
 876   module Disk_change : sig
 877     type reason = [
 878       | `MissingOnStart
 879       | `Unknown of int
 880     ]
 881
 882     type t = {
 883       old_src_path: string option; (** old source path *)
 884       new_src_path: string option; (** new source path *)
 885       dev_alias: string option;    (** device alias name *)
 886       reason: reason;              (** reason why this callback was called *)
 887     }
 888
 889     val to_string: t -> string
 890   end
 891
 892   module Tray_change : sig
 893     type reason = [
 894       | `Open
 895       | `Close
 896       | `Unknown of int
 897     ]
 898
 899     type t = {
 900       dev_alias: string option; (** device alias *)
 901       reason: reason;           (** why the tray status was changed *)
 902     }
 903
 904     val to_string: t -> string
 905   end
 906
 907   module PM_wakeup : sig
 908     type reason = [
 909       | `Unknown of int
 910     ]
 911
 912     type t = reason
 913
 914     val to_string: t -> string
 915   end
 916
 917   module PM_suspend : sig
 918     type reason = [
 919       | `Unknown of int
 920     ]
 921
 922     type t = reason
 923
 924     val to_string: t -> string
 925   end
 926
 927   module Balloon_change : sig
 928     type t = int64
 929
 930     val to_string: t -> string
 931   end
 932
 933   module PM_suspend_disk : sig
 934     type reason = [
 935       | `Unknown of int
 936     ]
 937
 938     type t = reason
 939
 940     val to_string: t -> string
 941   end
 942
 943
 944   type callback =
 945     | Lifecycle     of ([`R] Domain.t -> Lifecycle.t -> unit)
 946     | Reboot        of ([`R] Domain.t -> Reboot.t -> unit)
 947     | RtcChange     of ([`R] Domain.t -> Rtc_change.t -> unit)
 948     | Watchdog      of ([`R] Domain.t -> Watchdog.t -> unit)
 949     | IOError       of ([`R] Domain.t -> Io_error.t -> unit)
 950     | Graphics      of ([`R] Domain.t -> Graphics.t -> unit)
 951     | IOErrorReason of ([`R] Domain.t -> Io_error.t -> unit)
 952     | ControlError  of ([`R] Domain.t -> Control_error.t -> unit)
 953     | BlockJob      of ([`R] Domain.t -> Block_job.t -> unit)
 954     | DiskChange    of ([`R] Domain.t -> Disk_change.t -> unit)
 955     | TrayChange    of ([`R] Domain.t -> Tray_change.t -> unit)
 956     | PMWakeUp      of ([`R] Domain.t -> PM_wakeup.t -> unit)
 957     | PMSuspend     of ([`R] Domain.t -> PM_suspend.t -> unit)
 958     | BalloonChange of ([`R] Domain.t -> Balloon_change.t -> unit)
 959     | PMSuspendDisk of ([`R] Domain.t -> PM_suspend_disk.t -> unit)
 960
 961     (** type of a registered call back function *)
 962
 963   val register_default_impl : unit -> unit
 964     (** Registers the default event loop based on poll(). This
 965         must be done before connections are opened.
 966
 967         Once registered call run_default_impl in a loop. *)
 968
 969   val run_default_impl : unit -> unit
 970     (** Runs one iteration of the event loop. Applications will
 971         generally want to have a thread which invokes this in an
 972         infinite loop. *)
 973
 974   type callback_id
 975     (** an individual event registration *)
 976
 977   val register_any : 'a Connect.t -> ?dom:'a Domain.t -> callback -> callback_id
 978     (** [register_any con ?dom callback] registers [callback]
 979         to receive notification of arbitrary domain events. Return
 980         a registration id which can be used in [deregister_any].
 981
 982         If [?dom] is None then register for this kind of event on
 983         all domains. If [dom] is [Some d] then register for this
 984         kind of event only on [d].
 985     *)
 986
 987   val deregister_any : 'a Connect.t -> callback_id -> unit
 988     (** [deregister_any con id] deregisters the previously registered
 989         callback with id [id]. *)
 990
 991   type timer_id
 992     (** an individual timer event *)
 993
 994   val add_timeout : 'a Connect.t -> int -> (unit -> unit) -> timer_id
 995     (** [add_timeout con ms cb] registers [cb] as a timeout callback
 996         which will be called every [ms] milliseconds *)
 997
 998   val remove_timeout : 'a Connect.t -> timer_id -> unit
 999     (** [remove_timeout con t] deregisters timeout callback [t]. *)
1000
1001 end
1002   (** Module dealing with events generated by domain
1003       state changes. *)
1004
1005 (** {3 Networks} *)
1006
1007 module Network :
1008 sig
1009   type 'rw t
1010     (** Network handle.  Read-only handles have type [ro Network.t] and
1011         read-write handles have type [rw Network.t].
1012     *)
1013
1014   val lookup_by_name : 'a Connect.t -> string -> 'a t
1015     (** Lookup a network by name. *)
1016   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
1017     (** Lookup a network by (packed) UUID. *)
1018   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
1019     (** Lookup a network by UUID string. *)
1020   val create_xml : [>`W] Connect.t -> xml -> rw t
1021     (** Create a network. *)
1022   val define_xml : [>`W] Connect.t -> xml -> rw t
1023     (** Define but don't activate a network. *)
1024   val undefine : [>`W] t -> unit
1025     (** Undefine configuration of a network. *)
1026   val create : [>`W] t -> unit
1027     (** Start up a defined (inactive) network. *)
1028   val destroy : [>`W] t -> unit
1029     (** Destroy a network. *)
1030   val free : [>`R] t -> unit
1031     (** [free network] frees the network object in memory.
1032
1033         The network object is automatically freed if it is garbage
1034         collected.  This function just forces it to be freed right
1035         away.
1036     *)
1037
1038   val get_name : [>`R] t -> string
1039     (** Get network name. *)
1040   val get_uuid : [>`R] t -> uuid
1041     (** Get network packed UUID. *)
1042   val get_uuid_string : [>`R] t -> string
1043     (** Get network UUID as a printable string. *)
1044   val get_xml_desc : [>`R] t -> xml
1045     (** Get XML description of a network. *)
1046   val get_bridge_name : [>`R] t -> string
1047     (** Get bridge device name of a network. *)
1048   val get_autostart : [>`R] t -> bool
1049     (** Get the autostart flag for a network. *)
1050   val set_autostart : [>`W] t -> bool -> unit
1051     (** Set the autostart flag for a network. *)
1052
1053   external const : [>`R] t -> ro t = "%identity"
1054     (** [const network] turns a read/write network handle into a read-only
1055         network handle.  Note that the opposite operation is impossible.
1056       *)
1057 end
1058   (** Module dealing with networks.  [Network.t] is the
1059       network object. *)
1060
1061 (** {3 Storage pools} *)
1062
1063 module Pool :
1064 sig
1065   type 'rw t
1066     (** Storage pool handle. *)
1067
1068   type pool_state = Inactive | Building | Running | Degraded
1069     (** State of the storage pool. *)
1070
1071   type pool_build_flags = New | Repair | Resize
1072     (** Flags for creating a storage pool. *)
1073
1074   type pool_delete_flags = Normal | Zeroed
1075     (** Flags for deleting a storage pool. *)
1076
1077   type pool_info = {
1078     state : pool_state;                 (** Pool state. *)
1079     capacity : int64;                   (** Logical size in bytes. *)
1080     allocation : int64;                 (** Currently allocated in bytes. *)
1081     available : int64;                  (** Remaining free space bytes. *)
1082   }
1083
1084   val lookup_by_name : 'a Connect.t -> string -> 'a t
1085   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
1086   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
1087     (** Look up a storage pool by name, UUID or UUID string. *)
1088
1089   val create_xml : [>`W] Connect.t -> xml -> rw t
1090     (** Create a storage pool. *)
1091   val define_xml : [>`W] Connect.t -> xml -> rw t
1092     (** Define but don't activate a storage pool. *)
1093   val build : [>`W] t -> pool_build_flags -> unit
1094     (** Build a storage pool. *)
1095   val undefine : [>`W] t -> unit
1096     (** Undefine configuration of a storage pool. *)
1097   val create : [>`W] t -> unit
1098     (** Start up a defined (inactive) storage pool. *)
1099   val destroy : [>`W] t -> unit
1100     (** Destroy a storage pool. *)
1101   val delete : [>`W] t -> unit
1102     (** Delete a storage pool. *)
1103   val free : [>`R] t -> unit
1104     (** Free a storage pool object in memory.
1105
1106         The storage pool object is automatically freed if it is garbage
1107         collected.  This function just forces it to be freed right
1108         away.
1109     *)
1110   val refresh : [`R] t -> unit
1111     (** Refresh the list of volumes in the storage pool. *)
1112
1113   val get_name : [`R] t -> string
1114     (** Name of the pool. *)
1115   val get_uuid : [`R] t -> uuid
1116     (** Get the UUID (as a packed byte array). *)
1117   val get_uuid_string : [`R] t -> string
1118     (** Get the UUID (as a printable string). *)
1119   val get_info : [`R] t -> pool_info
1120     (** Get information about the pool. *)
1121   val get_xml_desc : [`R] t -> xml
1122     (** Get the XML description. *)
1123   val get_autostart : [`R] t -> bool
1124     (** Get the autostart flag for the storage pool. *)
1125   val set_autostart : [>`W] t -> bool -> unit
1126     (** Set the autostart flag for the storage pool. *)
1127
1128   val num_of_volumes : [`R] t -> int
1129     (** Returns the number of storage volumes within the storage pool. *)
1130   val list_volumes : [`R] t -> int -> string array
1131     (** Return list of storage volumes. *)
1132
1133   external const : [>`R] t -> ro t = "%identity"
1134     (** [const conn] turns a read/write storage pool into a read-only
1135         pool.  Note that the opposite operation is impossible.
1136       *)
1137 end
1138   (** Module dealing with storage pools. *)
1139
1140 (** {3 Storage volumes} *)
1141
1142 module Volume :
1143 sig
1144   type 'rw t
1145     (** Storage volume handle. *)
1146
1147   type vol_type = File | Block
1148     (** Type of a storage volume. *)
1149
1150   type vol_delete_flags = Normal | Zeroed
1151     (** Flags for deleting a storage volume. *)
1152
1153   type vol_info = {
1154     typ : vol_type;                     (** Type of storage volume. *)
1155     capacity : int64;                   (** Logical size in bytes. *)
1156     allocation : int64;                 (** Currently allocated in bytes. *)
1157   }
1158
1159   val lookup_by_name : 'a Pool.t -> string -> 'a t
1160   val lookup_by_key : 'a Connect.t -> string -> 'a t
1161   val lookup_by_path : 'a Connect.t -> string -> 'a t
1162     (** Look up a storage volume by name, key or path volume. *)
1163
1164   val pool_of_volume : 'a t -> 'a Pool.t
1165     (** Get the storage pool containing this volume. *)
1166
1167   val get_name : [`R] t -> string
1168     (** Name of the volume. *)
1169   val get_key : [`R] t -> string
1170     (** Key of the volume. *)
1171   val get_path : [`R] t -> string
1172     (** Path of the volume. *)
1173   val get_info : [`R] t -> vol_info
1174     (** Get information about the storage volume. *)
1175   val get_xml_desc : [`R] t -> xml
1176     (** Get the XML description. *)
1177
1178   val create_xml : [>`W] Pool.t -> xml -> unit
1179     (** Create a storage volume. *)
1180   val delete : [>`W] t -> vol_delete_flags -> unit
1181     (** Delete a storage volume. *)
1182   val free : [>`R] t -> unit
1183     (** Free a storage volume object in memory.
1184
1185         The storage volume object is automatically freed if it is garbage
1186         collected.  This function just forces it to be freed right
1187         away.
1188     *)
1189
1190   external const : [>`R] t -> ro t = "%identity"
1191     (** [const conn] turns a read/write storage volume into a read-only
1192         volume.  Note that the opposite operation is impossible.
1193       *)
1194 end
1195   (** Module dealing with storage volumes. *)
1196
1197 (** {3 Error handling and exceptions} *)
1198
1199 module Virterror :
1200 sig
1201   type code =
1202     | VIR_ERR_OK
1203     | VIR_ERR_INTERNAL_ERROR
1204     | VIR_ERR_NO_MEMORY
1205     | VIR_ERR_NO_SUPPORT
1206     | VIR_ERR_UNKNOWN_HOST
1207     | VIR_ERR_NO_CONNECT
1208     | VIR_ERR_INVALID_CONN
1209     | VIR_ERR_INVALID_DOMAIN
1210     | VIR_ERR_INVALID_ARG
1211     | VIR_ERR_OPERATION_FAILED
1212     | VIR_ERR_GET_FAILED
1213     | VIR_ERR_POST_FAILED
1214     | VIR_ERR_HTTP_ERROR
1215     | VIR_ERR_SEXPR_SERIAL
1216     | VIR_ERR_NO_XEN
1217     | VIR_ERR_XEN_CALL
1218     | VIR_ERR_OS_TYPE
1219     | VIR_ERR_NO_KERNEL
1220     | VIR_ERR_NO_ROOT
1221     | VIR_ERR_NO_SOURCE
1222     | VIR_ERR_NO_TARGET
1223     | VIR_ERR_NO_NAME
1224     | VIR_ERR_NO_OS
1225     | VIR_ERR_NO_DEVICE
1226     | VIR_ERR_NO_XENSTORE
1227     | VIR_ERR_DRIVER_FULL
1228     | VIR_ERR_CALL_FAILED
1229     | VIR_ERR_XML_ERROR
1230     | VIR_ERR_DOM_EXIST
1231     | VIR_ERR_OPERATION_DENIED
1232     | VIR_ERR_OPEN_FAILED
1233     | VIR_ERR_READ_FAILED
1234     | VIR_ERR_PARSE_FAILED
1235     | VIR_ERR_CONF_SYNTAX
1236     | VIR_ERR_WRITE_FAILED
1237     | VIR_ERR_XML_DETAIL
1238     | VIR_ERR_INVALID_NETWORK
1239     | VIR_ERR_NETWORK_EXIST
1240     | VIR_ERR_SYSTEM_ERROR
1241     | VIR_ERR_RPC
1242     | VIR_ERR_GNUTLS_ERROR
1243     | VIR_WAR_NO_NETWORK
1244     | VIR_ERR_NO_DOMAIN
1245     | VIR_ERR_NO_NETWORK
1246     | VIR_ERR_INVALID_MAC
1247     | VIR_ERR_AUTH_FAILED
1248     | VIR_ERR_INVALID_STORAGE_POOL
1249     | VIR_ERR_INVALID_STORAGE_VOL
1250     | VIR_WAR_NO_STORAGE
1251     | VIR_ERR_NO_STORAGE_POOL
1252     | VIR_ERR_NO_STORAGE_VOL
1253         (* ^^ NB: If you add a variant you MUST edit
1254            libvirt_c_epilogue.c:MAX_VIR_* *)
1255     | VIR_ERR_UNKNOWN of int
1256         (** See [<libvirt/virterror.h>] for meaning of these codes. *)
1257
1258   val string_of_code : code -> string
1259
1260   type domain =
1261     | VIR_FROM_NONE
1262     | VIR_FROM_XEN
1263     | VIR_FROM_XEND
1264     | VIR_FROM_XENSTORE
1265     | VIR_FROM_SEXPR
1266     | VIR_FROM_XML
1267     | VIR_FROM_DOM
1268     | VIR_FROM_RPC
1269     | VIR_FROM_PROXY
1270     | VIR_FROM_CONF
1271     | VIR_FROM_QEMU
1272     | VIR_FROM_NET
1273     | VIR_FROM_TEST
1274     | VIR_FROM_REMOTE
1275     | VIR_FROM_OPENVZ
1276     | VIR_FROM_XENXM
1277     | VIR_FROM_STATS_LINUX
1278     | VIR_FROM_STORAGE
1279         (* ^^ NB: If you add a variant you MUST edit
1280            libvirt_c_epilogue.c: MAX_VIR_* *)
1281     | VIR_FROM_UNKNOWN of int
1282         (** Subsystem / driver which produced the error. *)
1283
1284   val string_of_domain : domain -> string
1285
1286   type level =
1287     | VIR_ERR_NONE
1288     | VIR_ERR_WARNING
1289     | VIR_ERR_ERROR
1290         (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *)
1291     | VIR_ERR_UNKNOWN_LEVEL of int
1292         (** No error, a warning or an error. *)
1293
1294   val string_of_level : level -> string
1295
1296   type t = {
1297     code : code;                        (** Error code. *)
1298     domain : domain;                    (** Origin of the error. *)
1299     message : string option;            (** Human-readable message. *)
1300     level : level;                      (** Error or warning. *)
1301     str1 : string option;               (** Informational string. *)
1302     str2 : string option;               (** Informational string. *)
1303     str3 : string option;               (** Informational string. *)
1304     int1 : int32;                       (** Informational integer. *)
1305     int2 : int32;                       (** Informational integer. *)
1306   }
1307     (** An error object. *)
1308
1309   val to_string : t -> string
1310     (** Turn the exception into a printable string. *)
1311
1312   val get_last_error : unit -> t option
1313   val get_last_conn_error : [>`R] Connect.t -> t option
1314     (** Get the last error at a global or connection level.
1315
1316         Normally you do not need to use these functions because
1317         the library automatically turns errors into exceptions.
1318     *)
1319
1320   val reset_last_error : unit -> unit
1321   val reset_last_conn_error : [>`R] Connect.t -> unit
1322     (** Reset the error at a global or connection level.
1323
1324         Normally you do not need to use these functions.
1325     *)
1326
1327   val no_error : unit -> t
1328     (** Creates an empty error message.
1329
1330         Normally you do not need to use this function.
1331     *)
1332 end
1333   (** Module dealing with errors. *)
1334
1335 exception Virterror of Virterror.t
1336 (** This exception can be raised by any library function that detects
1337     an error.  To get a printable error message, call
1338     {!Virterror.to_string} on the content of this exception.
1339 *)
1340
1341 exception Not_supported of string
1342 (**
1343     Functions may raise
1344     [Not_supported "virFoo"]
1345     (where [virFoo] is the libvirt function name) if a function is
1346     not supported at either compile or run time.  This applies to
1347     any libvirt function added after version 0.2.1.
1348
1349     See also {{:http://libvirt.org/hvsupport.html}http://libvirt.org/hvsupport.html}
1350 *)
1351
1352 (** {3 Utility functions} *)
1353
1354 val map_ignore_errors : ('a -> 'b) -> 'a list -> 'b list
1355 (** [map_ignore_errors f xs] calls function [f] for each element of [xs].
1356
1357     This is just like [List.map] except that if [f x] throws a
1358     {!Virterror.t} exception, the error is ignored and [f x]
1359     is not returned in the final list.
1360
1361     This function is primarily useful when dealing with domains which
1362     might 'disappear' asynchronously from the currently running
1363     program.
1364 *)