libvirt/libvirt.mli

   1 (** OCaml bindings for libvirt. *)
   2 (* (C) Copyright 2007 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 is backwards and forwards compatible with
 146     any libvirt >= 0.2.1.  One consequence of this is that
 147     your program can dynamically link to a {i newer} version of
 148     libvirt than it was compiled with, and it should still
 149     work.
 150
 151     When we link to an older version of libvirt.so, there may
 152     be missing functions.  If ocaml-libvirt was compiled with
 153     gcc, then these are turned into OCaml {!Libvirt.Not_supported}
 154     exceptions.
 155
 156     We don't support libvirt < 0.2.1, and never will so don't ask us.
 157
 158     {3 Get list of domains and domain infos}
 159
 160     This is a very common operation, and libvirt supports various
 161     different methods to do it.  We have hidden the complexity in a
 162     flexible {!Libvirt.Domain.get_domains} and
 163     {!Libvirt.Domain.get_domains_and_infos} calls which is easy to use and
 164     automatically chooses the most efficient method depending on the
 165     version of libvirt in use.
 166
 167     {3 Threads}
 168
 169     You can issue multiple concurrent libvirt requests in
 170     different threads.  However you must follow this rule:
 171     Each thread must have its own separate libvirt connection, {i or}
 172     you must implement your own mutex scheme to ensure that no
 173     two threads can ever make concurrent calls using the same
 174     libvirt connection.
 175
 176     (Note that multithreaded code is not well tested.  If you find
 177     bugs please report them.)
 178
 179     {3 Initialisation}
 180
 181     Libvirt requires all callers to call virInitialize before
 182     using the library.  This is done automatically for you by
 183     these bindings when the program starts up, and we believe
 184     that the way this is done is safe.
 185
 186     {2 Reference}
 187 *)
 188
 189 type uuid = string
 190     (** This is a "raw" UUID, ie. a packed string of bytes. *)
 191
 192 type xml = string
 193     (** Type of XML (an uninterpreted string of bytes).  Use PXP, expat,
 194         xml-light, etc. if you want to do anything useful with the XML.
 195     *)
 196
 197 type filename = string
 198     (** A filename. *)
 199
 200 val get_version : ?driver:string -> unit -> int * int
 201   (** [get_version ()] returns the library version in the first part
 202       of the tuple, and [0] in the second part.
 203
 204       [get_version ~driver ()] returns the library version in the first
 205       part of the tuple, and the version of the driver called [driver]
 206       in the second part.
 207
 208       The version numbers are encoded as
 209       1,000,000 * major + 1,000 * minor + release.
 210   *)
 211
 212 val uuid_length : int
 213   (** Length of packed UUIDs. *)
 214
 215 val uuid_string_length : int
 216   (** Length of UUID strings. *)
 217
 218 type rw = [`R|`W]
 219 type ro = [`R]
 220     (** These
 221         {{:http://caml.inria.fr/pub/ml-archives/caml-list/2004/07/80683af867cce6bf8fff273973f70c95.en.html}phantom types}
 222         are used to ensure the type-safety of read-only
 223         versus read-write connections.
 224
 225         All connection/domain/etc. objects are marked with
 226         a phantom read-write or read-only type, and trying to
 227         pass a read-only object into a function which could
 228         mutate the object will cause a compile time error.
 229
 230         Each module provides a function like {!Libvirt.Connect.const}
 231         to demote a read-write object into a read-only object.  The
 232         opposite operation is, of course, not allowed.
 233
 234         If you want to handle both read-write and read-only
 235         connections at runtime, use a variant similar to this:
 236 {[
 237 type conn_t =
 238     | No_connection
 239     | Read_only of Libvirt.ro Libvirt.Connect.t
 240     | Read_write of Libvirt.rw Libvirt.Connect.t
 241 ]}
 242         See also the source of [mlvirsh].
 243     *)
 244
 245 (** {3 Forward definitions}
 246
 247     These definitions are placed here to avoid the need to
 248     use recursive module dependencies.
 249 *)
 250
 251 type ('a, 'b) job_t
 252 (** Forward definition of {!Job.t}. *)
 253
 254 (** {3 Connections} *)
 255
 256 module Connect :
 257 sig
 258   type 'rw t
 259     (** Connection.  Read-only connections have type [ro Connect.t] and
 260         read-write connections have type [rw Connect.t].
 261       *)
 262
 263   type node_info = {
 264     model : string;                     (** CPU model *)
 265     memory : int64;                     (** memory size in kilobytes *)
 266     cpus : int;                         (** number of active CPUs *)
 267     mhz : int;                          (** expected CPU frequency *)
 268     nodes : int;                        (** number of NUMA nodes (1 = UMA) *)
 269     sockets : int;                      (** number of CPU sockets per node *)
 270     cores : int;                        (** number of cores per socket *)
 271     threads : int;                      (** number of threads per core *)
 272   }
 273
 274   val connect : ?name:string -> unit -> rw t
 275   val connect_readonly : ?name:string -> unit -> ro t
 276     (** [connect ~name ()] connects to the hypervisor with URI [name].
 277
 278         [connect ()] connects to the default hypervisor.
 279
 280         [connect_readonly] is the same but connects in read-only mode.
 281     *)
 282
 283   val close : [>`R] t -> unit
 284     (** [close conn] closes and frees the connection object in memory.
 285
 286         The connection is automatically closed if it is garbage
 287         collected.  This function just forces it to be closed
 288         and freed right away.
 289     *)
 290
 291   val get_type : [>`R] t -> string
 292     (** Returns the name of the driver (hypervisor). *)
 293
 294   val get_version : [>`R] t -> int
 295     (** Returns the driver version
 296         [major * 1_000_000 + minor * 1000 + release]
 297     *)
 298   val get_hostname : [>`R] t -> string
 299     (** Returns the hostname of the physical server. *)
 300   val get_uri : [>`R] t -> string
 301     (** Returns the canonical connection URI. *)
 302   val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
 303     (** Returns the maximum number of virtual CPUs
 304         supported by a guest VM of a particular type. *)
 305   val list_domains : [>`R] t -> int -> int array
 306     (** [list_domains conn max] returns the running domain IDs,
 307         up to a maximum of [max] entries.
 308
 309         Call {!num_of_domains} first to get a value for [max].
 310
 311         See also:
 312         {!Libvirt.Domain.get_domains},
 313         {!Libvirt.Domain.get_domains_and_infos}.
 314     *)
 315   val num_of_domains : [>`R] t -> int
 316     (** Returns the number of running domains. *)
 317   val get_capabilities : [>`R] t -> xml
 318     (** Returns the hypervisor capabilities (as XML). *)
 319   val num_of_defined_domains : [>`R] t -> int
 320     (** Returns the number of inactive (shutdown) domains. *)
 321   val list_defined_domains : [>`R] t -> int -> string array
 322     (** [list_defined_domains conn max]
 323         returns the names of the inactive domains, up to
 324         a maximum of [max] entries.
 325
 326         Call {!num_of_defined_domains} first to get a value for [max].
 327
 328         See also:
 329         {!Libvirt.Domain.get_domains},
 330         {!Libvirt.Domain.get_domains_and_infos}.
 331     *)
 332   val num_of_networks : [>`R] t -> int
 333     (** Returns the number of networks. *)
 334   val list_networks : [>`R] t -> int -> string array
 335     (** [list_networks conn max]
 336         returns the names of the networks, up to a maximum
 337         of [max] entries.
 338         Call {!num_of_networks} first to get a value for [max].
 339     *)
 340   val num_of_defined_networks : [>`R] t -> int
 341     (** Returns the number of inactive networks. *)
 342   val list_defined_networks : [>`R] t -> int -> string array
 343     (** [list_defined_networks conn max]
 344         returns the names of the inactive networks, up to a maximum
 345         of [max] entries.
 346         Call {!num_of_defined_networks} first to get a value for [max].
 347     *)
 348
 349   val num_of_pools : [>`R] t -> int
 350     (** Returns the number of storage pools. *)
 351   val list_pools : [>`R] t -> int -> string array
 352     (** Return list of storage pools. *)
 353   val num_of_defined_pools : [>`R] t -> int
 354     (** Returns the number of storage pools. *)
 355   val list_defined_pools : [>`R] t -> int -> string array
 356     (** Return list of storage pools. *)
 357
 358     (* The name of this function is inconsistent, but the inconsistency
 359      * is really in libvirt itself.
 360      *)
 361   val get_node_info : [>`R] t -> node_info
 362     (** Return information about the physical server. *)
 363
 364   val node_get_free_memory : [> `R] t -> int64
 365     (**
 366        [node_get_free_memory conn]
 367        returns the amount of free memory (not allocated to any guest)
 368        in the machine.
 369     *)
 370
 371   val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array
 372     (**
 373        [node_get_cells_free_memory conn start max]
 374        returns the amount of free memory on each NUMA cell in kilobytes.
 375        [start] is the first cell for which we return free memory.
 376        [max] is the maximum number of cells for which we return free memory.
 377        Returns an array of up to [max] entries in length.
 378     *)
 379
 380   val maxcpus_of_node_info : node_info -> int
 381     (** Calculate the total number of CPUs supported (but not necessarily
 382         active) in the host.
 383     *)
 384
 385   val cpumaplen : int -> int
 386     (** Calculate the length (in bytes) required to store the complete
 387         CPU map between a single virtual and all physical CPUs of a domain.
 388     *)
 389
 390   val use_cpu : string -> int -> unit
 391     (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
 392   val unuse_cpu : string -> int -> unit
 393     (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
 394   val cpu_usable : string -> int -> int -> int -> bool
 395     (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
 396         [cpu] is usable by [vcpu]. *)
 397
 398   external const : [>`R] t -> ro t = "%identity"
 399     (** [const conn] turns a read/write connection into a read-only
 400         connection.  Note that the opposite operation is impossible.
 401       *)
 402 end
 403   (** Module dealing with connections.  [Connect.t] is the
 404       connection object. *)
 405
 406 (** {3 Domains} *)
 407
 408 module Domain :
 409 sig
 410   type 'rw t
 411     (** Domain handle.  Read-only handles have type [ro Domain.t] and
 412         read-write handles have type [rw Domain.t].
 413     *)
 414
 415   type state =
 416     | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
 417     | InfoShutdown | InfoShutoff | InfoCrashed
 418
 419   type info = {
 420     state : state;                      (** running state *)
 421     max_mem : int64;                    (** maximum memory in kilobytes *)
 422     memory : int64;                     (** memory used in kilobytes *)
 423     nr_virt_cpu : int;                  (** number of virtual CPUs *)
 424     cpu_time : int64;                   (** CPU time used in nanoseconds *)
 425   }
 426
 427   type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
 428
 429   type vcpu_info = {
 430     number : int;                       (** virtual CPU number *)
 431     vcpu_state : vcpu_state;            (** state *)
 432     vcpu_time : int64;                  (** CPU time used in nanoseconds *)
 433     cpu : int;                          (** real CPU number, -1 if offline *)
 434   }
 435
 436   type sched_param = string * sched_param_value
 437   and sched_param_value =
 438     | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
 439     | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
 440     | SchedFieldFloat of float | SchedFieldBool of bool
 441
 442   type migrate_flag = Live
 443
 444   type memory_flag = Virtual
 445
 446   type list_flag =
 447     | ListActive
 448     | ListInactive
 449     | ListAll
 450
 451   type block_stats = {
 452     rd_req : int64;
 453     rd_bytes : int64;
 454     wr_req : int64;
 455     wr_bytes : int64;
 456     errs : int64;
 457   }
 458
 459   type interface_stats = {
 460     rx_bytes : int64;
 461     rx_packets : int64;
 462     rx_errs : int64;
 463     rx_drop : int64;
 464     tx_bytes : int64;
 465     tx_packets : int64;
 466     tx_errs : int64;
 467     tx_drop : int64;
 468   }
 469
 470   val max_peek : [>`R] t -> int
 471     (** Maximum size supported by the {!block_peek} and {!memory_peek}
 472         functions.  If you want to peek more than this then you must
 473         break your request into chunks. *)
 474
 475   val list_all_domains : 'a Connect.t -> ?want_info:bool -> list_flag list -> 'a t array * info array
 476     (** [list_all_domains conn flags] returns all domains which
 477         match [flags].
 478
 479         This can return both active and inactive domains.  The
 480         list of flags controls what domains are returned.  See
 481         {!list_flag}.
 482
 483         The two arrays returned will have the same length, unless
 484         [~want_info] is [false] in which case the info array
 485         will be zero-length.  The default for [~want_info] is [true].
 486         In most cases there is no extra penalty for getting the
 487         info fields, or the penalty is insignificant.
 488
 489         This call was introduced in libvirt 0.4.5.  Because you
 490         might dynamically link to an older version of libvirt which
 491         doesn't have this call, you should use {!get_domains}
 492         or {!get_domains_and_infos} which use the most efficient
 493         way to get domains for the available version of libvirt.
 494     *)
 495   val create_linux : [>`W] Connect.t -> xml -> rw t
 496     (** Create a new guest domain (not necessarily a Linux one)
 497         from the given XML.
 498     *)
 499   val create_linux_job : [>`W] Connect.t -> xml -> ([`Domain], rw) job_t
 500     (** Asynchronous domain creation. *)
 501   val lookup_by_id : 'a Connect.t -> int -> 'a t
 502     (** Lookup a domain by ID. *)
 503   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
 504     (** Lookup a domain by UUID.  This uses the packed byte array UUID. *)
 505   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
 506     (** Lookup a domain by (string) UUID. *)
 507   val lookup_by_name : 'a Connect.t -> string -> 'a t
 508     (** Lookup a domain by name. *)
 509   val destroy : [>`W] t -> unit
 510     (** Abruptly destroy a domain. *)
 511   val free : [>`R] t -> unit
 512     (** [free domain] frees the domain object in memory.
 513
 514         The domain object is automatically freed if it is garbage
 515         collected.  This function just forces it to be freed right
 516         away.
 517     *)
 518
 519   val suspend : [>`W] t -> unit
 520     (** Suspend a domain. *)
 521   val resume : [>`W] t -> unit
 522     (** Resume a domain. *)
 523   val save : [>`W] t -> filename -> unit
 524     (** Suspend a domain, then save it to the file. *)
 525   val save_job : [>`W] t -> filename -> ([`Domain_nocreate], rw) job_t
 526     (** Asynchronous domain suspend. *)
 527   val restore : [>`W] Connect.t -> filename -> unit
 528     (** Restore a domain from a file. *)
 529   val restore_job : [>`W] Connect.t -> filename -> ([`Domain_nocreate], rw) job_t
 530     (** Asynchronous domain restore. *)
 531   val core_dump : [>`W] t -> filename -> unit
 532     (** Force a domain to core dump to the named file. *)
 533   val core_dump_job : [>`W] t -> filename -> ([`Domain_nocreate], rw) job_t
 534     (** Asynchronous core dump. *)
 535   val shutdown : [>`W] t -> unit
 536     (** Shutdown a domain. *)
 537   val reboot : [>`W] t -> unit
 538     (** Reboot a domain. *)
 539   val get_name : [>`R] t -> string
 540     (** Get the domain name. *)
 541   val get_uuid : [>`R] t -> uuid
 542     (** Get the domain UUID (as a packed byte array). *)
 543   val get_uuid_string : [>`R] t -> string
 544     (** Get the domain UUID (as a printable string). *)
 545   val get_id : [>`R] t -> int
 546     (** [getid dom] returns the ID of the domain.
 547
 548         Do not call this on a defined but not running domain.  Those
 549         domains don't have IDs, and you'll get an error here.
 550     *)
 551
 552   val get_os_type : [>`R] t -> string
 553     (** Get the operating system type. *)
 554   val get_max_memory : [>`R] t -> int64
 555     (** Get the maximum memory allocation. *)
 556   val set_max_memory : [>`W] t -> int64 -> unit
 557     (** Set the maximum memory allocation. *)
 558   val set_memory : [>`W] t -> int64 -> unit
 559     (** Set the normal memory allocation. *)
 560   val get_info : [>`R] t -> info
 561     (** Get information about a domain. *)
 562   val get_xml_desc : [>`R] t -> xml
 563     (** Get the XML description of a domain. *)
 564   val get_scheduler_type : [>`R] t -> string * int
 565     (** Get the scheduler type. *)
 566   val get_scheduler_parameters : [>`R] t -> int -> sched_param array
 567     (** Get the array of scheduler parameters. *)
 568   val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
 569     (** Set the array of scheduler parameters. *)
 570   val define_xml : [>`W] Connect.t -> xml -> rw t
 571     (** Define a new domain (but don't start it up) from the XML. *)
 572   val undefine : [>`W] t -> unit
 573     (** Undefine a domain - removes its configuration. *)
 574   val create : [>`W] t -> unit
 575     (** Launch a defined (inactive) domain. *)
 576   val create_job : [>`W] t -> ([`Domain_nocreate], rw) job_t
 577     (** Asynchronous launch domain. *)
 578   val get_autostart : [>`R] t -> bool
 579     (** Get the autostart flag for a domain. *)
 580   val set_autostart : [>`W] t -> bool -> unit
 581     (** Set the autostart flag for a domain. *)
 582   val set_vcpus : [>`W] t -> int -> unit
 583     (** Change the number of vCPUs available to a domain. *)
 584   val pin_vcpu : [>`W] t -> int -> string -> unit
 585     (** [pin_vcpu dom vcpu bitmap] pins a domain vCPU to a bitmap of physical
 586         CPUs.  See the libvirt documentation for details of the
 587         layout of the bitmap. *)
 588   val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
 589     (** [get_vcpus dom maxinfo maplen] returns the pinning information
 590         for a domain.  See the libvirt documentation for details
 591         of the array and bitmap returned from this function.
 592     *)
 593   val get_max_vcpus : [>`R] t -> int
 594     (** Returns the maximum number of vCPUs supported for this domain. *)
 595   val attach_device : [>`W] t -> xml -> unit
 596     (** Attach a device (described by the device XML) to a domain. *)
 597   val detach_device : [>`W] t -> xml -> unit
 598     (** Detach a device (described by the device XML) from a domain. *)
 599
 600   val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
 601     ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
 602     (** [migrate dom dconn flags ()] migrates a domain to a
 603         destination host described by [dconn].
 604
 605         The optional flag [?dname] is used to rename the domain.
 606
 607         The optional flag [?uri] is used to route the migration.
 608
 609         The optional flag [?bandwidth] is used to limit the bandwidth
 610         used for migration (in Mbps). *)
 611
 612   val block_stats : [>`R] t -> string -> block_stats
 613     (** Returns block device stats. *)
 614   val interface_stats : [>`R] t -> string -> interface_stats
 615     (** Returns network interface stats. *)
 616
 617   val block_peek : [>`R] t -> string -> int64 -> int -> string -> int -> unit
 618     (** [block_peek dom path offset size buf boff] reads [size] bytes at
 619         [offset] in the domain's [path] block device.
 620
 621         If successful then the data is written into [buf] starting
 622         at offset [boff], for [size] bytes.
 623
 624         See also {!max_peek}. *)
 625   val memory_peek : [>`R] t -> memory_flag list -> int64 -> int ->
 626     string -> int -> unit
 627     (** [memory_peek dom Virtual offset size] reads [size] bytes
 628         at [offset] in the domain's virtual memory.
 629
 630         If successful then the data is written into [buf] starting
 631         at offset [boff], for [size] bytes.
 632
 633         See also {!max_peek}. *)
 634
 635   external const : [>`R] t -> ro t = "%identity"
 636     (** [const dom] turns a read/write domain handle into a read-only
 637         domain handle.  Note that the opposite operation is impossible.
 638       *)
 639
 640   val get_domains : ([>`R] as 'a) Connect.t -> list_flag list -> 'a t list
 641     (** Get the active and/or inactive domains using the most
 642         efficient method available.
 643
 644         See also:
 645         {!get_domains_and_infos},
 646         {!list_all_domains},
 647         {!Connect.list_domains},
 648         {!Connect.list_defined_domains}.
 649   *)
 650
 651   val get_domains_and_infos : ([>`R] as 'a) Connect.t -> list_flag list ->
 652     ('a t * info) list
 653     (** This gets the active and/or inactive domains and the
 654         domain info for each one using the most efficient
 655         method available.
 656
 657         See also:
 658         {!get_domains},
 659         {!list_all_domains},
 660         {!Connect.list_domains},
 661         {!Connect.list_defined_domains},
 662         {!get_info}.
 663     *)
 664
 665 end
 666   (** Module dealing with domains.  [Domain.t] is the
 667       domain object. *)
 668
 669 (** {3 Networks} *)
 670
 671 module Network :
 672 sig
 673   type 'rw t
 674     (** Network handle.  Read-only handles have type [ro Network.t] and
 675         read-write handles have type [rw Network.t].
 676     *)
 677
 678   val lookup_by_name : 'a Connect.t -> string -> 'a t
 679     (** Lookup a network by name. *)
 680   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
 681     (** Lookup a network by (packed) UUID. *)
 682   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
 683     (** Lookup a network by UUID string. *)
 684   val create_xml : [>`W] Connect.t -> xml -> rw t
 685     (** Create a network. *)
 686   val create_xml_job : [>`W] Connect.t -> xml -> ([`Network], rw) job_t
 687     (** Asynchronous create network. *)
 688   val define_xml : [>`W] Connect.t -> xml -> rw t
 689     (** Define but don't activate a network. *)
 690   val undefine : [>`W] t -> unit
 691     (** Undefine configuration of a network. *)
 692   val create : [>`W] t -> unit
 693     (** Start up a defined (inactive) network. *)
 694   val create_job : [>`W] t -> ([`Network_nocreate], rw) job_t
 695     (** Asynchronous start network. *)
 696   val destroy : [>`W] t -> unit
 697     (** Destroy a network. *)
 698   val free : [>`R] t -> unit
 699     (** [free network] frees the network object in memory.
 700
 701         The network object is automatically freed if it is garbage
 702         collected.  This function just forces it to be freed right
 703         away.
 704     *)
 705
 706   val get_name : [>`R] t -> string
 707     (** Get network name. *)
 708   val get_uuid : [>`R] t -> uuid
 709     (** Get network packed UUID. *)
 710   val get_uuid_string : [>`R] t -> string
 711     (** Get network UUID as a printable string. *)
 712   val get_xml_desc : [>`R] t -> xml
 713     (** Get XML description of a network. *)
 714   val get_bridge_name : [>`R] t -> string
 715     (** Get bridge device name of a network. *)
 716   val get_autostart : [>`R] t -> bool
 717     (** Get the autostart flag for a network. *)
 718   val set_autostart : [>`W] t -> bool -> unit
 719     (** Set the autostart flag for a network. *)
 720
 721   external const : [>`R] t -> ro t = "%identity"
 722     (** [const network] turns a read/write network handle into a read-only
 723         network handle.  Note that the opposite operation is impossible.
 724       *)
 725 end
 726   (** Module dealing with networks.  [Network.t] is the
 727       network object. *)
 728
 729 (** {3 Storage pools} *)
 730
 731 module Pool :
 732 sig
 733   type 'rw t
 734     (** Storage pool handle. *)
 735
 736   type pool_state = Inactive | Building | Running | Degraded
 737     (** State of the storage pool. *)
 738
 739   type pool_build_flags = New | Repair | Resize
 740     (** Flags for creating a storage pool. *)
 741
 742   type pool_delete_flags = Normal | Zeroed
 743     (** Flags for deleting a storage pool. *)
 744
 745   type pool_info = {
 746     state : pool_state;                 (** Pool state. *)
 747     capacity : int64;                   (** Logical size in bytes. *)
 748     allocation : int64;                 (** Currently allocated in bytes. *)
 749     available : int64;                  (** Remaining free space bytes. *)
 750   }
 751
 752   val lookup_by_name : 'a Connect.t -> string -> 'a t
 753   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
 754   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
 755     (** Look up a storage pool by name, UUID or UUID string. *)
 756
 757   val create_xml : [>`W] Connect.t -> xml -> rw t
 758     (** Create a storage pool. *)
 759   val define_xml : [>`W] Connect.t -> xml -> rw t
 760     (** Define but don't activate a storage pool. *)
 761   val build : [>`W] t -> pool_build_flags -> unit
 762     (** Build a storage pool. *)
 763   val undefine : [>`W] t -> unit
 764     (** Undefine configuration of a storage pool. *)
 765   val create : [>`W] t -> unit
 766     (** Start up a defined (inactive) storage pool. *)
 767   val destroy : [>`W] t -> unit
 768     (** Destroy a storage pool. *)
 769   val delete : [>`W] t -> unit
 770     (** Delete a storage pool. *)
 771   val free : [>`R] t -> unit
 772     (** Free a storage pool object in memory.
 773
 774         The storage pool object is automatically freed if it is garbage
 775         collected.  This function just forces it to be freed right
 776         away.
 777     *)
 778   val refresh : [`R] t -> unit
 779     (** Refresh the list of volumes in the storage pool. *)
 780
 781   val get_name : [`R] t -> string
 782     (** Name of the pool. *)
 783   val get_uuid : [`R] t -> uuid
 784     (** Get the UUID (as a packed byte array). *)
 785   val get_uuid_string : [`R] t -> string
 786     (** Get the UUID (as a printable string). *)
 787   val get_info : [`R] t -> pool_info
 788     (** Get information about the pool. *)
 789   val get_xml_desc : [`R] t -> xml
 790     (** Get the XML description. *)
 791   val get_autostart : [`R] t -> bool
 792     (** Get the autostart flag for the storage pool. *)
 793   val set_autostart : [`W] t -> bool -> unit
 794     (** Set the autostart flag for the storage pool. *)
 795
 796   val num_of_volumes : [`R] t -> int
 797     (** Returns the number of storage volumes within the storage pool. *)
 798   val list_volumes : [`R] t -> int -> string array
 799     (** Return list of storage volumes. *)
 800
 801   external const : [>`R] t -> ro t = "%identity"
 802     (** [const conn] turns a read/write storage pool into a read-only
 803         pool.  Note that the opposite operation is impossible.
 804       *)
 805 end
 806   (** Module dealing with storage pools. *)
 807
 808 (** {3 Storage volumes} *)
 809
 810 module Volume :
 811 sig
 812   type 'rw t
 813     (** Storage volume handle. *)
 814
 815   type vol_type = File | Block
 816     (** Type of a storage volume. *)
 817
 818   type vol_delete_flags = Normal | Zeroed
 819     (** Flags for deleting a storage volume. *)
 820
 821   type vol_info = {
 822     typ : vol_type;                     (** Type of storage volume. *)
 823     capacity : int64;                   (** Logical size in bytes. *)
 824     allocation : int64;                 (** Currently allocated in bytes. *)
 825   }
 826
 827   val lookup_by_name : 'a Pool.t -> string -> 'a t
 828   val lookup_by_key : 'a Connect.t -> string -> 'a t
 829   val lookup_by_path : 'a Connect.t -> string -> 'a t
 830     (** Look up a storage volume by name, key or path volume. *)
 831
 832   val pool_of_volume : 'a t -> 'a Pool.t
 833     (** Get the storage pool containing this volume. *)
 834
 835   val get_name : [`R] t -> string
 836     (** Name of the volume. *)
 837   val get_key : [`R] t -> string
 838     (** Key of the volume. *)
 839   val get_path : [`R] t -> string
 840     (** Path of the volume. *)
 841   val get_info : [`R] t -> vol_info
 842     (** Get information about the storage volume. *)
 843   val get_xml_desc : [`R] t -> xml
 844     (** Get the XML description. *)
 845
 846   val create_xml : [`W] Pool.t -> xml -> unit
 847     (** Create a storage volume. *)
 848   val delete : [`W] t -> unit
 849     (** Delete a storage volume. *)
 850   val free : [>`R] t -> unit
 851     (** Free a storage volume object in memory.
 852
 853         The storage volume object is automatically freed if it is garbage
 854         collected.  This function just forces it to be freed right
 855         away.
 856     *)
 857
 858   external const : [>`R] t -> ro t = "%identity"
 859     (** [const conn] turns a read/write storage volume into a read-only
 860         volume.  Note that the opposite operation is impossible.
 861       *)
 862 end
 863   (** Module dealing with storage volumes. *)
 864
 865 (** {3 Jobs and asynchronous processing} *)
 866
 867 module Job :
 868 sig
 869   type ('jobclass, 'rw) t = ('jobclass, 'rw) job_t
 870     (** A background asynchronous job.
 871
 872         Jobs represent a pending operation such as domain creation.
 873         The possible types for a job are:
 874
 875 {v
 876 (`Domain, `W) Job.t            Job creating a new domain
 877 (`Domain_nocreate, `W) Job.t   Job acting on an existing domain
 878 (`Network, `W) Job.t           Job creating a new network
 879 (`Network_nocreate, `W) Job.t  Job acting on an existing network
 880 v}
 881       *)
 882
 883   type job_type = Bounded | Unbounded
 884     (** A Bounded job is one where we can estimate time to completion. *)
 885
 886   type job_state = Running | Complete | Failed | Cancelled
 887     (** State of the job. *)
 888
 889   type job_info = {
 890     typ : job_type;                     (** Job type (Bounded, Unbounded) *)
 891     state : job_state;                  (** Job state (Running, etc.) *)
 892     running_time : int;                 (** Actual running time (seconds) *)
 893     (** The following fields are only available in Bounded jobs: *)
 894     remaining_time : int;               (** Estimated time left (seconds) *)
 895     percent_complete : int              (** Estimated percent complete *)
 896   }
 897
 898   val get_info : ('a,'b) t -> job_info
 899     (** Get information and status about the job. *)
 900
 901   val get_domain : ([`Domain], 'a) t -> 'a Domain.t
 902     (** Get the completed domain from a job.
 903
 904         You should only call it on a job in state Complete. *)
 905
 906   val get_network : ([`Network], 'a) t -> 'a Network.t
 907     (** Get the completed network from a job.
 908
 909         You should only call it on a job in state Complete. *)
 910
 911   val cancel : ('a,'b) t -> unit
 912     (** Cancel a job. *)
 913
 914   val free : ('a, [>`R]) t -> unit
 915     (** Free a job object in memory.
 916
 917         The job object is automatically freed if it is garbage
 918         collected.  This function just forces it to be freed right
 919         away.
 920     *)
 921
 922   external const : ('a, [>`R]) t -> ('a, ro) t = "%identity"
 923     (** [const conn] turns a read/write job into a read-only
 924         job.  Note that the opposite operation is impossible.
 925       *)
 926 end
 927   (** Module dealing with asynchronous jobs. *)
 928
 929 (** {3 Error handling and exceptions} *)
 930
 931 module Virterror :
 932 sig
 933   type code =
 934     | VIR_ERR_OK
 935     | VIR_ERR_INTERNAL_ERROR
 936     | VIR_ERR_NO_MEMORY
 937     | VIR_ERR_NO_SUPPORT
 938     | VIR_ERR_UNKNOWN_HOST
 939     | VIR_ERR_NO_CONNECT
 940     | VIR_ERR_INVALID_CONN
 941     | VIR_ERR_INVALID_DOMAIN
 942     | VIR_ERR_INVALID_ARG
 943     | VIR_ERR_OPERATION_FAILED
 944     | VIR_ERR_GET_FAILED
 945     | VIR_ERR_POST_FAILED
 946     | VIR_ERR_HTTP_ERROR
 947     | VIR_ERR_SEXPR_SERIAL
 948     | VIR_ERR_NO_XEN
 949     | VIR_ERR_XEN_CALL
 950     | VIR_ERR_OS_TYPE
 951     | VIR_ERR_NO_KERNEL
 952     | VIR_ERR_NO_ROOT
 953     | VIR_ERR_NO_SOURCE
 954     | VIR_ERR_NO_TARGET
 955     | VIR_ERR_NO_NAME
 956     | VIR_ERR_NO_OS
 957     | VIR_ERR_NO_DEVICE
 958     | VIR_ERR_NO_XENSTORE
 959     | VIR_ERR_DRIVER_FULL
 960     | VIR_ERR_CALL_FAILED
 961     | VIR_ERR_XML_ERROR
 962     | VIR_ERR_DOM_EXIST
 963     | VIR_ERR_OPERATION_DENIED
 964     | VIR_ERR_OPEN_FAILED
 965     | VIR_ERR_READ_FAILED
 966     | VIR_ERR_PARSE_FAILED
 967     | VIR_ERR_CONF_SYNTAX
 968     | VIR_ERR_WRITE_FAILED
 969     | VIR_ERR_XML_DETAIL
 970     | VIR_ERR_INVALID_NETWORK
 971     | VIR_ERR_NETWORK_EXIST
 972     | VIR_ERR_SYSTEM_ERROR
 973     | VIR_ERR_RPC
 974     | VIR_ERR_GNUTLS_ERROR
 975     | VIR_WAR_NO_NETWORK
 976     | VIR_ERR_NO_DOMAIN
 977     | VIR_ERR_NO_NETWORK
 978     | VIR_ERR_INVALID_MAC
 979     | VIR_ERR_AUTH_FAILED
 980     | VIR_ERR_INVALID_STORAGE_POOL
 981     | VIR_ERR_INVALID_STORAGE_VOL
 982     | VIR_WAR_NO_STORAGE
 983     | VIR_ERR_NO_STORAGE_POOL
 984     | VIR_ERR_NO_STORAGE_VOL
 985         (* ^^ NB: If you add a variant you MUST edit
 986            libvirt_c_epilogue.c:MAX_VIR_* *)
 987     | VIR_ERR_UNKNOWN of int
 988         (** See [<libvirt/virterror.h>] for meaning of these codes. *)
 989
 990   val string_of_code : code -> string
 991
 992   type domain =
 993     | VIR_FROM_NONE
 994     | VIR_FROM_XEN
 995     | VIR_FROM_XEND
 996     | VIR_FROM_XENSTORE
 997     | VIR_FROM_SEXPR
 998     | VIR_FROM_XML
 999     | VIR_FROM_DOM
1000     | VIR_FROM_RPC
1001     | VIR_FROM_PROXY
1002     | VIR_FROM_CONF
1003     | VIR_FROM_QEMU
1004     | VIR_FROM_NET
1005     | VIR_FROM_TEST
1006     | VIR_FROM_REMOTE
1007     | VIR_FROM_OPENVZ
1008     | VIR_FROM_XENXM
1009     | VIR_FROM_STATS_LINUX
1010     | VIR_FROM_STORAGE
1011         (* ^^ NB: If you add a variant you MUST edit
1012            libvirt_c_epilogue.c: MAX_VIR_* *)
1013     | VIR_FROM_UNKNOWN of int
1014         (** Subsystem / driver which produced the error. *)
1015
1016   val string_of_domain : domain -> string
1017
1018   type level =
1019     | VIR_ERR_NONE
1020     | VIR_ERR_WARNING
1021     | VIR_ERR_ERROR
1022         (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *)
1023     | VIR_ERR_UNKNOWN_LEVEL of int
1024         (** No error, a warning or an error. *)
1025
1026   val string_of_level : level -> string
1027
1028   type t = {
1029     code : code;                        (** Error code. *)
1030     domain : domain;                    (** Origin of the error. *)
1031     message : string option;            (** Human-readable message. *)
1032     level : level;                      (** Error or warning. *)
1033     str1 : string option;               (** Informational string. *)
1034     str2 : string option;               (** Informational string. *)
1035     str3 : string option;               (** Informational string. *)
1036     int1 : int32;                       (** Informational integer. *)
1037     int2 : int32;                       (** Informational integer. *)
1038   }
1039     (** An error object. *)
1040
1041   val to_string : t -> string
1042     (** Turn the exception into a printable string. *)
1043
1044   val get_last_error : unit -> t option
1045   val get_last_conn_error : [>`R] Connect.t -> t option
1046     (** Get the last error at a global or connection level.
1047
1048         Normally you do not need to use these functions because
1049         the library automatically turns errors into exceptions.
1050     *)
1051
1052   val reset_last_error : unit -> unit
1053   val reset_last_conn_error : [>`R] Connect.t -> unit
1054     (** Reset the error at a global or connection level.
1055
1056         Normally you do not need to use these functions.
1057     *)
1058
1059   val no_error : unit -> t
1060     (** Creates an empty error message.
1061
1062         Normally you do not need to use this function.
1063     *)
1064 end
1065   (** Module dealing with errors. *)
1066
1067 exception Virterror of Virterror.t
1068 (** This exception can be raised by any library function that detects
1069     an error.  To get a printable error message, call
1070     {!Virterror.to_string} on the content of this exception.
1071 *)
1072
1073 exception Not_supported of string
1074 (**
1075     Functions may raise
1076     [Not_supported "virFoo"]
1077     (where [virFoo] is the libvirt function name) if a function is
1078     not supported at either compile or run time.  This applies to
1079     any libvirt function added after version 0.2.1.
1080
1081     See also {{:http://libvirt.org/hvsupport.html}http://libvirt.org/hvsupport.html}
1082 *)
1083
1084 (** {3 Utility functions} *)
1085
1086 val map_ignore_errors : ('a -> 'b) -> 'a list -> 'b list
1087 (** [map_ignore_errors f xs] calls function [f] for each element of [xs].
1088
1089     This is just like [List.map] except that if [f x] throws a
1090     {!Virterror.t} exception, the error is ignored and [f x]
1091     is not returned in the final list.
1092
1093     This function is primarily useful when dealing with domains which
1094     might 'disappear' asynchronously from the currently running
1095     program.
1096 *)