1 (** OCaml bindings for libvirt. *)
2 (* (C) Copyright 2007 Richard W.M. Jones, Red Hat Inc.
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.
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.
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
21 {2 Introduction and examples}
23 This is a set of bindings for writing OCaml programs to
24 manage virtual machines through {{:http://libvirt.org/}libvirt}.
26 {3 Using libvirt interactively}
28 Using the interactive toplevel:
32 Objective Caml version 3.10.0
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}
48 {3 Compiling libvirt programs}
50 This command compiles a program to native code:
53 ocamlopt -I +libvirt mllibvirt.cmxa list_domains.ml -o list_domains
56 {3 Example: Connect to the hypervisor}
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:
64 module C = Libvirt.Connect
65 module D = Libvirt.Domain
66 module N = Libvirt.Network
69 To get a connection handle, assuming a Xen hypervisor:
73 let conn = C.connect_readonly ~name ()
76 {3 Example: List running domains}
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
86 printf "%8d %s\n%!" (D.get_id dom) (D.get_name dom)
90 {3 Example: List inactive domains}
93 let n = C.num_of_defined_domains conn in
94 let names = C.list_defined_domains conn n in
97 printf "inactive %s\n%!" name
101 {3 Example: Print node info}
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;
114 let hostname = C.get_hostname conn in
115 printf "hostname = %s\n%!" hostname;
117 let uri = C.get_uri conn in
118 printf "uri = %s\n%!" uri
124 (** {2 Programming issues}
126 {3 General safety issues}
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.
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.
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.
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.
152 {3 Backwards and forwards compatibility}
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
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}
165 We don't support libvirt < 0.2.1, and never will so don't ask us.
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
176 (Note that multithreaded code is not well tested. If you find
177 bugs please report them.)
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.
190 (** This is a "raw" UUID, ie. a packed string of bytes. *)
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.
197 type filename = string
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.
204 [get_version ~driver ()] returns the library version in the first
205 part of the tuple, and the version of the driver called [driver]
208 The version numbers are encoded as
209 1,000,000 * major + 1,000 * minor + release.
212 val uuid_length : int
213 (** Length of packed UUIDs. *)
215 val uuid_string_length : int
216 (** Length of UUID strings. *)
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.
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.
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.
234 If you want to handle both read-write and read-only
235 connections at runtime, use a variant similar to this:
239 | Read_only of Libvirt.ro Libvirt.Connect.t
240 | Read_write of Libvirt.rw Libvirt.Connect.t
242 See also the source of [mlvirsh].
246 (** Forward definition of {!Job.t} to avoid recursive module dependencies. *)
248 (** {3 Connections} *)
253 (** Connection. Read-only connections have type [ro Connect.t] and
254 read-write connections have type [rw Connect.t].
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 *)
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].
272 [connect ()] connects to the default hypervisor.
274 [connect_readonly] is the same but connects in read-only mode.
277 val close : [>`R] t -> unit
278 (** [close conn] closes and frees the connection object in memory.
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.
285 val get_type : [>`R] t -> string
286 (** Returns the name of the driver (hypervisor). *)
288 val get_version : [>`R] t -> int
289 (** Returns the driver version
290 [major * 1_000_000 + minor * 1000 + release]
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].
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].
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
322 Call {!num_of_networks} first to get a value for [max].
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
330 Call {!num_of_defined_networks} first to get a value for [max].
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. *)
342 (* The name of this function is inconsistent, but the inconsistency
343 * is really in libvirt itself.
345 val get_node_info : [>`R] t -> node_info
346 (** Return information about the physical server. *)
348 val node_get_free_memory : [> `R] t -> int64
350 [node_get_free_memory conn]
351 returns the amount of free memory (not allocated to any guest)
355 val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array
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.
364 val maxcpus_of_node_info : node_info -> int
365 (** Calculate the total number of CPUs supported (but not necessarily
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.
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]. *)
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.
387 (** Module dealing with connections. [Connect.t] is the
388 connection object. *)
395 (** Domain handle. Read-only handles have type [ro Domain.t] and
396 read-write handles have type [rw Domain.t].
400 | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
401 | InfoShutdown | InfoShutoff | InfoCrashed
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 *)
411 type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
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 *)
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
426 type migrate_flag = Live
436 type interface_stats = {
447 val create_linux : [>`W] Connect.t -> xml -> rw t
448 (** Create a new guest domain (not necessarily a Linux one)
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.
466 The domain object is automatically freed if it is garbage
467 collected. This function just forces it to be freed right
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.
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.
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.
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. *)
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].
557 The optional flag [?dname] is used to rename the domain.
559 The optional flag [?uri] is used to route the migration.
561 The optional flag [?bandwidth] is used to limit the bandwidth
562 used for migration (in Mbps). *)
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. *)
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.
574 (** Module dealing with domains. [Domain.t] is the
582 (** Network handle. Read-only handles have type [ro Network.t] and
583 read-write handles have type [rw Network.t].
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.
609 The network object is automatically freed if it is garbage
610 collected. This function just forces it to be freed right
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. *)
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.
634 (** Module dealing with networks. [Network.t] is the
637 (** {3 Storage pools} *)
642 (** Storage pool handle. *)
644 type pool_state = Inactive | Building | Running | Degraded
645 (** State of the storage pool. *)
647 type pool_build_flags = New | Repair | Resize
648 (** Flags for creating a storage pool. *)
650 type pool_delete_flags = Normal | Zeroed
651 (** Flags for deleting a storage pool. *)
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. *)
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. *)
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.
682 The storage pool object is automatically freed if it is garbage
683 collected. This function just forces it to be freed right
686 val refresh : [`R] t -> unit
687 (** Refresh the list of volumes in the storage pool. *)
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. *)
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. *)
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.
714 (** Module dealing with storage pools. *)
716 (** {3 Storage volumes} *)
721 (** Storage volume handle. *)
723 type vol_type = File | Block
724 (** Type of a storage volume. *)
726 type vol_delete_flags = Normal | Zeroed
727 (** Flags for deleting a storage volume. *)
730 typ : vol_type; (** Type of storage volume. *)
731 capacity : int64; (** Logical size in bytes. *)
732 allocation : int64; (** Currently allocated in bytes. *)
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. *)
740 val pool_of_volume : 'a t -> 'a Pool.t
741 (** Get the storage pool containing this volume. *)
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. *)
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.
761 The storage volume object is automatically freed if it is garbage
762 collected. This function just forces it to be freed right
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.
771 (** Module dealing with storage volumes. *)
773 (** {3 Jobs and asynchronous processing} *)
777 type ('jobclass, 'rw) t = ('jobclass, 'rw) job_t
778 (** A background asynchronous job.
780 Jobs represent a pending operation such as domain creation.
781 The possible types for a job are:
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
791 type job_type = Bounded | Unbounded
792 (** A Bounded job is one where we can estimate time to completion. *)
794 type job_state = Running | Complete | Failed | Cancelled
795 (** State of the job. *)
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 *)
806 val get_info : ('a,'b) t -> job_info
807 (** Get information and status about the job. *)
809 val get_domain : ([`Domain], 'a) t -> 'a Domain.t
810 (** Get the completed domain from a job.
812 You should only call it on a job in state Complete. *)
814 val get_network : ([`Network], 'a) t -> 'a Network.t
815 (** Get the completed network from a job.
817 You should only call it on a job in state Complete. *)
819 val cancel : ('a,'b) t -> unit
822 val free : ('a, [>`R]) t -> unit
823 (** Free a job object in memory.
825 The job object is automatically freed if it is garbage
826 collected. This function just forces it to be freed right
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.
835 (** Module dealing with asynchronous jobs. *)
837 (** {3 Error handling and exceptions} *)
843 | VIR_ERR_INTERNAL_ERROR
846 | VIR_ERR_UNKNOWN_HOST
848 | VIR_ERR_INVALID_CONN
849 | VIR_ERR_INVALID_DOMAIN
850 | VIR_ERR_INVALID_ARG
851 | VIR_ERR_OPERATION_FAILED
853 | VIR_ERR_POST_FAILED
855 | VIR_ERR_SEXPR_SERIAL
866 | VIR_ERR_NO_XENSTORE
867 | VIR_ERR_DRIVER_FULL
868 | VIR_ERR_CALL_FAILED
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
878 | VIR_ERR_INVALID_NETWORK
879 | VIR_ERR_NETWORK_EXIST
880 | VIR_ERR_SYSTEM_ERROR
882 | VIR_ERR_GNUTLS_ERROR
886 | VIR_ERR_INVALID_MAC
887 | VIR_ERR_AUTH_FAILED
888 | VIR_ERR_INVALID_STORAGE_POOL
889 | VIR_ERR_INVALID_STORAGE_VOL
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. *)
898 val string_of_code : code -> string
917 | VIR_FROM_STATS_LINUX
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. *)
924 val string_of_domain : domain -> string
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. *)
934 val string_of_level : level -> string
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. *)
950 (** An error object. *)
952 val to_string : t -> string
953 (** Turn the exception into a printable string. *)
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.
959 Normally you do not need to use these functions because
960 the library automatically turns errors into exceptions.
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.
967 Normally you do not need to use these functions.
970 val no_error : unit -> t
971 (** Creates an empty error message.
973 Normally you do not need to use this function.
976 (** Module dealing with errors. *)
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.
984 exception Not_supported of string
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.
992 See also {{:http://libvirt.org/hvsupport.html}http://libvirt.org/hvsupport.html}