libvirt/libvirt.mli

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