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
  10    This library is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13    Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public
  16    License along with this library; if not, write to the Free Software
  17    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
  18 *)
  19
  20 (**
  21    {2 Introduction and examples}
  22
  23    This is a set of bindings for writing OCaml programs to
  24    manage virtual machines through {{:http://libvirt.org/}libvirt}.
  25
  26    {3 Using libvirt interactively}
  27
  28    Using the interactive toplevel:
  29
  30 {v
  31 $ ocaml -I +libvirt
  32         Objective Caml version 3.10.0
  33
  34 # #load "unix.cma";;
  35 # #load "mllibvirt.cma";;
  36 # let name = "test:///default";;
  37 val name : string = "test:///default"
  38 # let conn = Libvirt.Connect.connect_readonly ~name () ;;
  39 val conn : Libvirt.ro Libvirt.Connect.t = <abstr>
  40 # Libvirt.Connect.get_node_info conn;;
  41   : Libvirt.Connect.node_info =
  42 {Libvirt.Connect.model = "i686"; Libvirt.Connect.memory = 3145728L;
  43  Libvirt.Connect.cpus = 16; Libvirt.Connect.mhz = 1400;
  44  Libvirt.Connect.nodes = 2; Libvirt.Connect.sockets = 2;
  45  Libvirt.Connect.cores = 2; Libvirt.Connect.threads = 2}
  46 v}
  47
  48    {3 Compiling libvirt programs}
  49
  50    This command compiles a program to native code:
  51
  52 {v
  53 ocamlopt -I +libvirt mllibvirt.cmxa list_domains.ml -o list_domains
  54 v}
  55
  56    {3 Example: Connect to the hypervisor}
  57
  58    The main modules are {!Libvirt.Connect}, {!Libvirt.Domain} and
  59    {!Libvirt.Network} corresponding respectively to the
  60    {{:http://libvirt.org/html/libvirt-libvirt.html}virConnect*, virDomain* and virNetwork* functions from libvirt}.
  61    For brevity I usually rename these modules like this:
  62
  63 {v
  64 module C = Libvirt.Connect
  65 module D = Libvirt.Domain
  66 module N = Libvirt.Network
  67 v}
  68
  69    To get a connection handle, assuming a Xen hypervisor:
  70
  71 {v
  72 let name = "xen:///"
  73 let conn = C.connect_readonly ~name ()
  74 v}
  75
  76    {3 Example: List running domains}
  77
  78 {v
  79 open Printf
  80
  81 let n = C.num_of_domains conn in
  82 let ids = C.list_domains conn n in
  83 let domains = Array.map (D.lookup_by_id conn) ids in
  84 Array.iter (
  85   fun dom ->
  86     printf "%8d %s\n%!" (D.get_id dom) (D.get_name dom)
  87 ) domains;
  88 v}
  89
  90    {3 Example: List inactive domains}
  91
  92 {v
  93 let n = C.num_of_defined_domains conn in
  94 let names = C.list_defined_domains conn n in
  95 Array.iter (
  96   fun name ->
  97     printf "inactive %s\n%!" name
  98 ) names;
  99 v}
 100
 101    {3 Example: Print node info}
 102
 103 {v
 104 let node_info = C.get_node_info conn in
 105 printf "model = %s\n" node_info.C.model;
 106 printf "memory = %Ld K\n" node_info.C.memory;
 107 printf "cpus = %d\n" node_info.C.cpus;
 108 printf "mhz = %d\n" node_info.C.mhz;
 109 printf "nodes = %d\n" node_info.C.nodes;
 110 printf "sockets = %d\n" node_info.C.sockets;
 111 printf "cores = %d\n" node_info.C.cores;
 112 printf "threads = %d\n%!" node_info.C.threads;
 113
 114 let hostname = C.get_hostname conn in
 115 printf "hostname = %s\n%!" hostname;
 116
 117 let uri = C.get_uri conn in
 118 printf "uri = %s\n%!" uri
 119 v}
 120
 121 *)
 122
 123
 124 (** {2 Programming issues}
 125
 126     {3 General safety issues}
 127
 128     Memory allocation / automatic garbage collection of all libvirt
 129     objects should be completely safe (except in the specific
 130     virterror case noted below).  If you find any safety issues or if your
 131     pure OCaml program ever segfaults, please contact the author.
 132
 133     You can force a libvirt object to be freed early by calling
 134     the [close] function on the object.  This shouldn't affect
 135     the safety of garbage collection and should only be used when
 136     you want to explicitly free memory.  Note that explicitly
 137     closing a connection object does nothing if there are still
 138     unclosed domain or network objects referencing it.
 139
 140     Note that even though you hold open (eg) a domain object, that
 141     doesn't mean that the domain (virtual machine) actually exists.
 142     The domain could have been shut down or deleted by another user.
 143     Thus domain objects can through odd exceptions at any time.
 144     This is just the nature of virtualisation.
 145
 146     Virterror has a specific design error which means that the
 147     objects embedded in a virterror exception message are only
 148     valid as long as the connection handle is still open.  This
 149     is a design flaw in the C code of libvirt and we cannot fix
 150     or work around it in the OCaml bindings.
 151
 152     {3 Backwards and forwards compatibility}
 153
 154     OCaml-libvirt is backwards and forwards compatible with
 155     any libvirt >= 0.2.1.  One consequence of this is that
 156     your program can dynamically link to a {i newer} version of
 157     libvirt than it was compiled with, and it should still
 158     work.
 159
 160     When we link to an older version of libvirt.so, there may
 161     be missing functions.  If ocaml-libvirt was compiled with
 162     gcc, then these are turned into OCaml {!Libvirt.Not_supported}
 163     exceptions.
 164
 165     We don't support libvirt < 0.2.1, and never will so don't ask us.
 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 {v
 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 v}
 242         See also the source of [mlvirsh].
 243     *)
 244
 245 type ('a, 'b) job_t
 246 (** Forward definition of {!Job.t} to avoid recursive module dependencies. *)
 247
 248 (** {3 Connections} *)
 249
 250 module Connect :
 251 sig
 252   type 'rw t
 253     (** Connection.  Read-only connections have type [ro Connect.t] and
 254         read-write connections have type [rw Connect.t].
 255       *)
 256
 257   type node_info = {
 258     model : string;                     (** CPU model *)
 259     memory : int64;                     (** memory size in kilobytes *)
 260     cpus : int;                         (** number of active CPUs *)
 261     mhz : int;                          (** expected CPU frequency *)
 262     nodes : int;                        (** number of NUMA nodes (1 = UMA) *)
 263     sockets : int;                      (** number of CPU sockets per node *)
 264     cores : int;                        (** number of cores per socket *)
 265     threads : int;                      (** number of threads per core *)
 266   }
 267
 268   val connect : ?name:string -> unit -> rw t
 269   val connect_readonly : ?name:string -> unit -> ro t
 270     (** [connect ~name ()] connects to the hypervisor with URI [name].
 271
 272         [connect ()] connects to the default hypervisor.
 273
 274         [connect_readonly] is the same but connects in read-only mode.
 275     *)
 276
 277   val close : [>`R] t -> unit
 278     (** [close conn] closes and frees the connection object in memory.
 279
 280         The connection is automatically closed if it is garbage
 281         collected.  This function just forces it to be closed
 282         and freed right away.
 283     *)
 284
 285   val get_type : [>`R] t -> string
 286     (** Returns the name of the driver (hypervisor). *)
 287
 288   val get_version : [>`R] t -> int
 289     (** Returns the driver version
 290         [major * 1_000_000 + minor * 1000 + release]
 291     *)
 292   val get_hostname : [>`R] t -> string
 293     (** Returns the hostname of the physical server. *)
 294   val get_uri : [>`R] t -> string
 295     (** Returns the canonical connection URI. *)
 296   val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
 297     (** Returns the maximum number of virtual CPUs
 298         supported by a guest VM of a particular type. *)
 299   val list_domains : [>`R] t -> int -> int array
 300     (** [list_domains conn max] returns the running domain IDs,
 301         up to a maximum of [max] entries.
 302         Call {!num_of_domains} first to get a value for [max].
 303     *)
 304   val num_of_domains : [>`R] t -> int
 305     (** Returns the number of running domains. *)
 306   val get_capabilities : [>`R] t -> xml
 307     (** Returns the hypervisor capabilities (as XML). *)
 308   val num_of_defined_domains : [>`R] t -> int
 309     (** Returns the number of inactive (shutdown) domains. *)
 310   val list_defined_domains : [>`R] t -> int -> string array
 311     (** [list_defined_domains conn max]
 312         returns the names of the inactive domains, up to
 313         a maximum of [max] entries.
 314         Call {!num_of_defined_domains} first to get a value for [max].
 315     *)
 316   val num_of_networks : [>`R] t -> int
 317     (** Returns the number of networks. *)
 318   val list_networks : [>`R] t -> int -> string array
 319     (** [list_networks conn max]
 320         returns the names of the networks, up to a maximum
 321         of [max] entries.
 322         Call {!num_of_networks} first to get a value for [max].
 323     *)
 324   val num_of_defined_networks : [>`R] t -> int
 325     (** Returns the number of inactive networks. *)
 326   val list_defined_networks : [>`R] t -> int -> string array
 327     (** [list_defined_networks conn max]
 328         returns the names of the inactive networks, up to a maximum
 329         of [max] entries.
 330         Call {!num_of_defined_networks} first to get a value for [max].
 331     *)
 332
 333   val num_of_pools : [>`R] t -> int
 334     (** Returns the number of storage pools. *)
 335   val list_pools : [>`R] t -> int -> string array
 336     (** Return list of storage pools. *)
 337   val num_of_defined_pools : [>`R] t -> int
 338     (** Returns the number of storage pools. *)
 339   val list_defined_pools : [>`R] t -> int -> string array
 340     (** Return list of storage pools. *)
 341
 342     (* The name of this function is inconsistent, but the inconsistency
 343      * is really in libvirt itself.
 344      *)
 345   val get_node_info : [>`R] t -> node_info
 346     (** Return information about the physical server. *)
 347
 348   val node_get_free_memory : [> `R] t -> int64
 349     (**
 350        [node_get_free_memory conn]
 351        returns the amount of free memory (not allocated to any guest)
 352        in the machine.
 353     *)
 354
 355   val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array
 356     (**
 357        [node_get_cells_free_memory conn start max]
 358        returns the amount of free memory on each NUMA cell in kilobytes.
 359        [start] is the first cell for which we return free memory.
 360        [max] is the maximum number of cells for which we return free memory.
 361        Returns an array of up to [max] entries in length.
 362     *)
 363
 364   val maxcpus_of_node_info : node_info -> int
 365     (** Calculate the total number of CPUs supported (but not necessarily
 366         active) in the host.
 367     *)
 368
 369   val cpumaplen : int -> int
 370     (** Calculate the length (in bytes) required to store the complete
 371         CPU map between a single virtual and all physical CPUs of a domain.
 372     *)
 373
 374   val use_cpu : string -> int -> unit
 375     (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
 376   val unuse_cpu : string -> int -> unit
 377     (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
 378   val cpu_usable : string -> int -> int -> int -> bool
 379     (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
 380         [cpu] is usable by [vcpu]. *)
 381
 382   external const : [>`R] t -> ro t = "%identity"
 383     (** [const conn] turns a read/write connection into a read-only
 384         connection.  Note that the opposite operation is impossible.
 385       *)
 386 end
 387   (** Module dealing with connections.  [Connect.t] is the
 388       connection object. *)
 389
 390 (** {3 Domains} *)
 391
 392 module Domain :
 393 sig
 394   type 'rw t
 395     (** Domain handle.  Read-only handles have type [ro Domain.t] and
 396         read-write handles have type [rw Domain.t].
 397     *)
 398
 399   type state =
 400     | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
 401     | InfoShutdown | InfoShutoff | InfoCrashed
 402
 403   type info = {
 404     state : state;                      (** running state *)
 405     max_mem : int64;                    (** maximum memory in kilobytes *)
 406     memory : int64;                     (** memory used in kilobytes *)
 407     nr_virt_cpu : int;                  (** number of virtual CPUs *)
 408     cpu_time : int64;                   (** CPU time used in nanoseconds *)
 409   }
 410
 411   type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
 412
 413   type vcpu_info = {
 414     number : int;                       (** virtual CPU number *)
 415     vcpu_state : vcpu_state;            (** state *)
 416     vcpu_time : int64;                  (** CPU time used in nanoseconds *)
 417     cpu : int;                          (** real CPU number, -1 if offline *)
 418   }
 419
 420   type sched_param = string * sched_param_value
 421   and sched_param_value =
 422     | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
 423     | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
 424     | SchedFieldFloat of float | SchedFieldBool of bool
 425
 426   type migrate_flag = Live
 427
 428   type block_stats = {
 429     rd_req : int64;
 430     rd_bytes : int64;
 431     wr_req : int64;
 432     wr_bytes : int64;
 433     errs : int64;
 434   }
 435
 436   type interface_stats = {
 437     rx_bytes : int64;
 438     rx_packets : int64;
 439     rx_errs : int64;
 440     rx_drop : int64;
 441     tx_bytes : int64;
 442     tx_packets : int64;
 443     tx_errs : int64;
 444     tx_drop : int64;
 445   }
 446
 447   val create_linux : [>`W] Connect.t -> xml -> rw t
 448     (** Create a new guest domain (not necessarily a Linux one)
 449         from the given XML.
 450     *)
 451   val create_linux_job : [>`W] Connect.t -> xml -> ([`Domain], rw) job_t
 452     (** Asynchronous domain creation. *)
 453   val lookup_by_id : 'a Connect.t -> int -> 'a t
 454     (** Lookup a domain by ID. *)
 455   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
 456     (** Lookup a domain by UUID.  This uses the packed byte array UUID. *)
 457   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
 458     (** Lookup a domain by (string) UUID. *)
 459   val lookup_by_name : 'a Connect.t -> string -> 'a t
 460     (** Lookup a domain by name. *)
 461   val destroy : [>`W] t -> unit
 462     (** Abruptly destroy a domain. *)
 463   val free : [>`R] t -> unit
 464     (** [free domain] frees the domain object in memory.
 465
 466         The domain object is automatically freed if it is garbage
 467         collected.  This function just forces it to be freed right
 468         away.
 469     *)
 470
 471   val suspend : [>`W] t -> unit
 472     (** Suspend a domain. *)
 473   val resume : [>`W] t -> unit
 474     (** Resume a domain. *)
 475   val save : [>`W] t -> filename -> unit
 476     (** Suspend a domain, then save it to the file. *)
 477   val save_job : [>`W] t -> filename -> ([`Domain_nocreate], rw) job_t
 478     (** Asynchronous domain suspend. *)
 479   val restore : [>`W] Connect.t -> filename -> unit
 480     (** Restore a domain from a file. *)
 481   val restore_job : [>`W] Connect.t -> filename -> ([`Domain_nocreate], rw) job_t
 482     (** Asynchronous domain restore. *)
 483   val core_dump : [>`W] t -> filename -> unit
 484     (** Force a domain to core dump to the named file. *)
 485   val core_dump_job : [>`W] t -> filename -> ([`Domain_nocreate], rw) job_t
 486     (** Asynchronous core dump. *)
 487   val shutdown : [>`W] t -> unit
 488     (** Shutdown a domain. *)
 489   val reboot : [>`W] t -> unit
 490     (** Reboot a domain. *)
 491   val get_name : [>`R] t -> string
 492     (** Get the domain name. *)
 493   val get_uuid : [>`R] t -> uuid
 494     (** Get the domain UUID (as a packed byte array). *)
 495   val get_uuid_string : [>`R] t -> string
 496     (** Get the domain UUID (as a printable string). *)
 497   val get_id : [>`R] t -> int
 498     (** [getid dom] returns the ID of the domain.
 499
 500         Do not call this on a defined but not running domain.  Those
 501         domains don't have IDs, and you'll get an error here.
 502     *)
 503
 504   val get_os_type : [>`R] t -> string
 505     (** Get the operating system type. *)
 506   val get_max_memory : [>`R] t -> int64
 507     (** Get the maximum memory allocation. *)
 508   val set_max_memory : [>`W] t -> int64 -> unit
 509     (** Set the maximum memory allocation. *)
 510   val set_memory : [>`W] t -> int64 -> unit
 511     (** Set the normal memory allocation. *)
 512   val get_info : [>`R] t -> info
 513     (** Get information about a domain. *)
 514   val get_xml_desc : [>`R] t -> xml
 515     (** Get the XML description of a domain. *)
 516   val get_scheduler_type : [>`R] t -> string * int
 517     (** Get the scheduler type. *)
 518   val get_scheduler_parameters : [>`R] t -> int -> sched_param array
 519     (** Get the array of scheduler parameters. *)
 520   val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
 521     (** Set the array of scheduler parameters. *)
 522   val define_xml : [>`W] Connect.t -> xml -> rw t
 523     (** Define a new domain (but don't start it up) from the XML. *)
 524   val undefine : [>`W] t -> unit
 525     (** Undefine a domain - removes its configuration. *)
 526   val create : [>`W] t -> unit
 527     (** Launch a defined (inactive) domain. *)
 528   val create_job : [>`W] t -> ([`Domain_nocreate], rw) job_t
 529     (** Asynchronous launch domain. *)
 530   val get_autostart : [>`R] t -> bool
 531     (** Get the autostart flag for a domain. *)
 532   val set_autostart : [>`W] t -> bool -> unit
 533     (** Set the autostart flag for a domain. *)
 534   val set_vcpus : [>`W] t -> int -> unit
 535     (** Change the number of vCPUs available to a domain. *)
 536   val pin_vcpu : [>`W] t -> int -> string -> unit
 537     (** [pin_vcpu dom vcpu bitmap] pins a domain vCPU to a bitmap of physical
 538         CPUs.  See the libvirt documentation for details of the
 539         layout of the bitmap. *)
 540   val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
 541     (** [get_vcpus dom maxinfo maplen] returns the pinning information
 542         for a domain.  See the libvirt documentation for details
 543         of the array and bitmap returned from this function.
 544     *)
 545   val get_max_vcpus : [>`R] t -> int
 546     (** Returns the maximum number of vCPUs supported for this domain. *)
 547   val attach_device : [>`W] t -> xml -> unit
 548     (** Attach a device (described by the device XML) to a domain. *)
 549   val detach_device : [>`W] t -> xml -> unit
 550     (** Detach a device (described by the device XML) from a domain. *)
 551
 552   val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
 553     ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
 554     (** [migrate dom dconn flags ()] migrates a domain to a
 555         destination host described by [dconn].
 556
 557         The optional flag [?dname] is used to rename the domain.
 558
 559         The optional flag [?uri] is used to route the migration.
 560
 561         The optional flag [?bandwidth] is used to limit the bandwidth
 562         used for migration (in Mbps). *)
 563
 564   val block_stats : [>`R] t -> string -> block_stats
 565     (** Returns block device stats. *)
 566   val interface_stats : [>`R] t -> string -> interface_stats
 567     (** Returns network interface stats. *)
 568
 569   external const : [>`R] t -> ro t = "%identity"
 570     (** [const dom] turns a read/write domain handle into a read-only
 571         domain handle.  Note that the opposite operation is impossible.
 572       *)
 573 end
 574   (** Module dealing with domains.  [Domain.t] is the
 575       domain object. *)
 576
 577 (** {3 Networks} *)
 578
 579 module Network :
 580 sig
 581   type 'rw t
 582     (** Network handle.  Read-only handles have type [ro Network.t] and
 583         read-write handles have type [rw Network.t].
 584     *)
 585
 586   val lookup_by_name : 'a Connect.t -> string -> 'a t
 587     (** Lookup a network by name. *)
 588   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
 589     (** Lookup a network by (packed) UUID. *)
 590   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
 591     (** Lookup a network by UUID string. *)
 592   val create_xml : [>`W] Connect.t -> xml -> rw t
 593     (** Create a network. *)
 594   val create_xml_job : [>`W] Connect.t -> xml -> ([`Network], rw) job_t
 595     (** Asynchronous create network. *)
 596   val define_xml : [>`W] Connect.t -> xml -> rw t
 597     (** Define but don't activate a network. *)
 598   val undefine : [>`W] t -> unit
 599     (** Undefine configuration of a network. *)
 600   val create : [>`W] t -> unit
 601     (** Start up a defined (inactive) network. *)
 602   val create_job : [>`W] t -> ([`Network_nocreate], rw) job_t
 603     (** Asynchronous start network. *)
 604   val destroy : [>`W] t -> unit
 605     (** Destroy a network. *)
 606   val free : [>`R] t -> unit
 607     (** [free network] frees the network object in memory.
 608
 609         The network object is automatically freed if it is garbage
 610         collected.  This function just forces it to be freed right
 611         away.
 612     *)
 613
 614   val get_name : [>`R] t -> string
 615     (** Get network name. *)
 616   val get_uuid : [>`R] t -> uuid
 617     (** Get network packed UUID. *)
 618   val get_uuid_string : [>`R] t -> string
 619     (** Get network UUID as a printable string. *)
 620   val get_xml_desc : [>`R] t -> xml
 621     (** Get XML description of a network. *)
 622   val get_bridge_name : [>`R] t -> string
 623     (** Get bridge device name of a network. *)
 624   val get_autostart : [>`R] t -> bool
 625     (** Get the autostart flag for a network. *)
 626   val set_autostart : [>`W] t -> bool -> unit
 627     (** Set the autostart flag for a network. *)
 628
 629   external const : [>`R] t -> ro t = "%identity"
 630     (** [const network] turns a read/write network handle into a read-only
 631         network handle.  Note that the opposite operation is impossible.
 632       *)
 633 end
 634   (** Module dealing with networks.  [Network.t] is the
 635       network object. *)
 636
 637 (** {3 Storage pools} *)
 638
 639 module Pool :
 640 sig
 641   type 'rw t
 642     (** Storage pool handle. *)
 643
 644   type pool_state = Inactive | Building | Running | Degraded
 645     (** State of the storage pool. *)
 646
 647   type pool_build_flags = New | Repair | Resize
 648     (** Flags for creating a storage pool. *)
 649
 650   type pool_delete_flags = Normal | Zeroed
 651     (** Flags for deleting a storage pool. *)
 652
 653   type pool_info = {
 654     state : pool_state;                 (** Pool state. *)
 655     capacity : int64;                   (** Logical size in bytes. *)
 656     allocation : int64;                 (** Currently allocated in bytes. *)
 657     available : int64;                  (** Remaining free space bytes. *)
 658   }
 659
 660   val lookup_by_name : 'a Connect.t -> string -> 'a t
 661   val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
 662   val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
 663     (** Look up a storage pool by name, UUID or UUID string. *)
 664
 665   val create_xml : [>`W] Connect.t -> xml -> rw t
 666     (** Create a storage pool. *)
 667   val define_xml : [>`W] Connect.t -> xml -> rw t
 668     (** Define but don't activate a storage pool. *)
 669   val build : [>`W] t -> pool_build_flags -> unit
 670     (** Build a storage pool. *)
 671   val undefine : [>`W] t -> unit
 672     (** Undefine configuration of a storage pool. *)
 673   val create : [>`W] t -> unit
 674     (** Start up a defined (inactive) storage pool. *)
 675   val destroy : [>`W] t -> unit
 676     (** Destroy a storage pool. *)
 677   val delete : [>`W] t -> unit
 678     (** Delete a storage pool. *)
 679   val free : [>`R] t -> unit
 680     (** Free a storage pool object in memory.
 681
 682         The storage pool object is automatically freed if it is garbage
 683         collected.  This function just forces it to be freed right
 684         away.
 685     *)
 686   val refresh : [`R] t -> unit
 687     (** Refresh the list of volumes in the storage pool. *)
 688
 689   val get_name : [`R] t -> string
 690     (** Name of the pool. *)
 691   val get_uuid : [`R] t -> uuid
 692     (** Get the UUID (as a packed byte array). *)
 693   val get_uuid_string : [`R] t -> string
 694     (** Get the UUID (as a printable string). *)
 695   val get_info : [`R] t -> pool_info
 696     (** Get information about the pool. *)
 697   val get_xml_desc : [`R] t -> xml
 698     (** Get the XML description. *)
 699   val get_autostart : [`R] t -> bool
 700     (** Get the autostart flag for the storage pool. *)
 701   val set_autostart : [`W] t -> bool -> unit
 702     (** Set the autostart flag for the storage pool. *)
 703
 704   val num_of_volumes : [`R] t -> int
 705     (** Returns the number of storage volumes within the storage pool. *)
 706   val list_volumes : [`R] t -> int -> string array
 707     (** Return list of storage volumes. *)
 708
 709   external const : [>`R] t -> ro t = "%identity"
 710     (** [const conn] turns a read/write storage pool into a read-only
 711         pool.  Note that the opposite operation is impossible.
 712       *)
 713 end
 714   (** Module dealing with storage pools. *)
 715
 716 (** {3 Storage volumes} *)
 717
 718 module Volume :
 719 sig
 720   type 'rw t
 721     (** Storage volume handle. *)
 722
 723   type vol_type = File | Block
 724     (** Type of a storage volume. *)
 725
 726   type vol_delete_flags = Normal | Zeroed
 727     (** Flags for deleting a storage volume. *)
 728
 729   type vol_info = {
 730     typ : vol_type;                     (** Type of storage volume. *)
 731     capacity : int64;                   (** Logical size in bytes. *)
 732     allocation : int64;                 (** Currently allocated in bytes. *)
 733   }
 734
 735   val lookup_by_name : 'a Pool.t -> string -> 'a t
 736   val lookup_by_key : 'a Connect.t -> string -> 'a t
 737   val lookup_by_path : 'a Connect.t -> string -> 'a t
 738     (** Look up a storage volume by name, key or path volume. *)
 739
 740   val pool_of_volume : 'a t -> 'a Pool.t
 741     (** Get the storage pool containing this volume. *)
 742
 743   val get_name : [`R] t -> string
 744     (** Name of the volume. *)
 745   val get_key : [`R] t -> string
 746     (** Key of the volume. *)
 747   val get_path : [`R] t -> string
 748     (** Path of the volume. *)
 749   val get_info : [`R] t -> vol_info
 750     (** Get information about the storage volume. *)
 751   val get_xml_desc : [`R] t -> xml
 752     (** Get the XML description. *)
 753
 754   val create_xml : [`W] Pool.t -> xml -> unit
 755     (** Create a storage volume. *)
 756   val delete : [`W] t -> unit
 757     (** Delete a storage volume. *)
 758   val free : [>`R] t -> unit
 759     (** Free a storage volume object in memory.
 760
 761         The storage volume object is automatically freed if it is garbage
 762         collected.  This function just forces it to be freed right
 763         away.
 764     *)
 765
 766   external const : [>`R] t -> ro t = "%identity"
 767     (** [const conn] turns a read/write storage volume into a read-only
 768         volume.  Note that the opposite operation is impossible.
 769       *)
 770 end
 771   (** Module dealing with storage volumes. *)
 772
 773 (** {3 Jobs and asynchronous processing} *)
 774
 775 module Job :
 776 sig
 777   type ('jobclass, 'rw) t = ('jobclass, 'rw) job_t
 778     (** A background asynchronous job.
 779
 780         Jobs represent a pending operation such as domain creation.
 781         The possible types for a job are:
 782
 783 {v
 784 (`Domain, `W) Job.t            Job creating a new domain
 785 (`Domain_nocreate, `W) Job.t   Job acting on an existing domain
 786 (`Network, `W) Job.t           Job creating a new network
 787 (`Network_nocreate, `W) Job.t  Job acting on an existing network
 788 v}
 789       *)
 790
 791   type job_type = Bounded | Unbounded
 792     (** A Bounded job is one where we can estimate time to completion. *)
 793
 794   type job_state = Running | Complete | Failed | Cancelled
 795     (** State of the job. *)
 796
 797   type job_info = {
 798     typ : job_type;                     (** Job type (Bounded, Unbounded) *)
 799     state : job_state;                  (** Job state (Running, etc.) *)
 800     running_time : int;                 (** Actual running time (seconds) *)
 801     (** The following fields are only available in Bounded jobs: *)
 802     remaining_time : int;               (** Estimated time left (seconds) *)
 803     percent_complete : int              (** Estimated percent complete *)
 804   }
 805
 806   val get_info : ('a,'b) t -> job_info
 807     (** Get information and status about the job. *)
 808
 809   val get_domain : ([`Domain], 'a) t -> 'a Domain.t
 810     (** Get the completed domain from a job.
 811
 812         You should only call it on a job in state Complete. *)
 813
 814   val get_network : ([`Network], 'a) t -> 'a Network.t
 815     (** Get the completed network from a job.
 816
 817         You should only call it on a job in state Complete. *)
 818
 819   val cancel : ('a,'b) t -> unit
 820     (** Cancel a job. *)
 821
 822   val free : ('a, [>`R]) t -> unit
 823     (** Free a job object in memory.
 824
 825         The job object is automatically freed if it is garbage
 826         collected.  This function just forces it to be freed right
 827         away.
 828     *)
 829
 830   external const : ('a, [>`R]) t -> ('a, ro) t = "%identity"
 831     (** [const conn] turns a read/write job into a read-only
 832         job.  Note that the opposite operation is impossible.
 833       *)
 834 end
 835   (** Module dealing with asynchronous jobs. *)
 836
 837 (** {3 Error handling and exceptions} *)
 838
 839 module Virterror :
 840 sig
 841   type code =
 842     | VIR_ERR_OK
 843     | VIR_ERR_INTERNAL_ERROR
 844     | VIR_ERR_NO_MEMORY
 845     | VIR_ERR_NO_SUPPORT
 846     | VIR_ERR_UNKNOWN_HOST
 847     | VIR_ERR_NO_CONNECT
 848     | VIR_ERR_INVALID_CONN
 849     | VIR_ERR_INVALID_DOMAIN
 850     | VIR_ERR_INVALID_ARG
 851     | VIR_ERR_OPERATION_FAILED
 852     | VIR_ERR_GET_FAILED
 853     | VIR_ERR_POST_FAILED
 854     | VIR_ERR_HTTP_ERROR
 855     | VIR_ERR_SEXPR_SERIAL
 856     | VIR_ERR_NO_XEN
 857     | VIR_ERR_XEN_CALL
 858     | VIR_ERR_OS_TYPE
 859     | VIR_ERR_NO_KERNEL
 860     | VIR_ERR_NO_ROOT
 861     | VIR_ERR_NO_SOURCE
 862     | VIR_ERR_NO_TARGET
 863     | VIR_ERR_NO_NAME
 864     | VIR_ERR_NO_OS
 865     | VIR_ERR_NO_DEVICE
 866     | VIR_ERR_NO_XENSTORE
 867     | VIR_ERR_DRIVER_FULL
 868     | VIR_ERR_CALL_FAILED
 869     | VIR_ERR_XML_ERROR
 870     | VIR_ERR_DOM_EXIST
 871     | VIR_ERR_OPERATION_DENIED
 872     | VIR_ERR_OPEN_FAILED
 873     | VIR_ERR_READ_FAILED
 874     | VIR_ERR_PARSE_FAILED
 875     | VIR_ERR_CONF_SYNTAX
 876     | VIR_ERR_WRITE_FAILED
 877     | VIR_ERR_XML_DETAIL
 878     | VIR_ERR_INVALID_NETWORK
 879     | VIR_ERR_NETWORK_EXIST
 880     | VIR_ERR_SYSTEM_ERROR
 881     | VIR_ERR_RPC
 882     | VIR_ERR_GNUTLS_ERROR
 883     | VIR_WAR_NO_NETWORK
 884     | VIR_ERR_NO_DOMAIN
 885     | VIR_ERR_NO_NETWORK
 886     | VIR_ERR_INVALID_MAC
 887     | VIR_ERR_AUTH_FAILED
 888     | VIR_ERR_INVALID_STORAGE_POOL
 889     | VIR_ERR_INVALID_STORAGE_VOL
 890     | VIR_WAR_NO_STORAGE
 891     | VIR_ERR_NO_STORAGE_POOL
 892     | VIR_ERR_NO_STORAGE_VOL
 893         (* ^^ NB: If you add a variant you MUST edit
 894            libvirt_c_epilogue.c:MAX_VIR_* *)
 895     | VIR_ERR_UNKNOWN of int
 896         (** See [<libvirt/virterror.h>] for meaning of these codes. *)
 897
 898   val string_of_code : code -> string
 899
 900   type domain =
 901     | VIR_FROM_NONE
 902     | VIR_FROM_XEN
 903     | VIR_FROM_XEND
 904     | VIR_FROM_XENSTORE
 905     | VIR_FROM_SEXPR
 906     | VIR_FROM_XML
 907     | VIR_FROM_DOM
 908     | VIR_FROM_RPC
 909     | VIR_FROM_PROXY
 910     | VIR_FROM_CONF
 911     | VIR_FROM_QEMU
 912     | VIR_FROM_NET
 913     | VIR_FROM_TEST
 914     | VIR_FROM_REMOTE
 915     | VIR_FROM_OPENVZ
 916     | VIR_FROM_XENXM
 917     | VIR_FROM_STATS_LINUX
 918     | VIR_FROM_STORAGE
 919         (* ^^ NB: If you add a variant you MUST edit
 920            libvirt_c_epilogue.c: MAX_VIR_* *)
 921     | VIR_FROM_UNKNOWN of int
 922         (** Subsystem / driver which produced the error. *)
 923
 924   val string_of_domain : domain -> string
 925
 926   type level =
 927     | VIR_ERR_NONE
 928     | VIR_ERR_WARNING
 929     | VIR_ERR_ERROR
 930         (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *)
 931     | VIR_ERR_UNKNOWN_LEVEL of int
 932         (** No error, a warning or an error. *)
 933
 934   val string_of_level : level -> string
 935
 936   type t = {
 937     code : code;                        (** Error code. *)
 938     domain : domain;                    (** Origin of the error. *)
 939     message : string option;            (** Human-readable message. *)
 940     level : level;                      (** Error or warning. *)
 941     conn : ro Connect.t option;         (** Associated connection. *)
 942     dom : ro Domain.t option;           (** Associated domain. *)
 943     str1 : string option;               (** Informational string. *)
 944     str2 : string option;               (** Informational string. *)
 945     str3 : string option;               (** Informational string. *)
 946     int1 : int32;                       (** Informational integer. *)
 947     int2 : int32;                       (** Informational integer. *)
 948     net : ro Network.t option;          (** Associated network. *)
 949   }
 950     (** An error object. *)
 951
 952   val to_string : t -> string
 953     (** Turn the exception into a printable string. *)
 954
 955   val get_last_error : unit -> t option
 956   val get_last_conn_error : [>`R] Connect.t -> t option
 957     (** Get the last error at a global or connection level.
 958
 959         Normally you do not need to use these functions because
 960         the library automatically turns errors into exceptions.
 961     *)
 962
 963   val reset_last_error : unit -> unit
 964   val reset_last_conn_error : [>`R] Connect.t -> unit
 965     (** Reset the error at a global or connection level.
 966
 967         Normally you do not need to use these functions.
 968     *)
 969
 970   val no_error : unit -> t
 971     (** Creates an empty error message.
 972
 973         Normally you do not need to use this function.
 974     *)
 975 end
 976   (** Module dealing with errors. *)
 977
 978 exception Virterror of Virterror.t
 979 (** This exception can be raised by any library function that detects
 980     an error.  To get a printable error message, call
 981     {!Virterror.to_string} on the content of this exception.
 982 *)
 983
 984 exception Not_supported of string
 985 (**
 986     Functions may raise
 987     [Not_supported "virFoo"]
 988     (where [virFoo] is the libvirt function name) if a function is
 989     not supported at either compile or run time.  This applies to
 990     any libvirt function added after version 0.2.1.
 991
 992     See also {{:http://libvirt.org/hvsupport.html}http://libvirt.org/hvsupport.html}
 993 *)
 994