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. If you find any safety issues
130 or if your pure OCaml program ever segfaults, please contact the author.
132 You can force a libvirt object to be freed early by calling
133 the [close] function on the object. This shouldn't affect
134 the safety of garbage collection and should only be used when
135 you want to explicitly free memory. Note that explicitly
136 closing a connection object does nothing if there are still
137 unclosed domain or network objects referencing it.
139 Note that even though you hold open (eg) a domain object, that
140 doesn't mean that the domain (virtual machine) actually exists.
141 The domain could have been shut down or deleted by another user.
142 Thus domain objects can through odd exceptions at any time.
143 This is just the nature of virtualisation.
145 {3 Backwards and forwards compatibility}
147 OCaml-libvirt is backwards and forwards compatible with
148 any libvirt >= 0.2.1. One consequence of this is that
149 your program can dynamically link to a {i newer} version of
150 libvirt than it was compiled with, and it should still
153 When we link to an older version of libvirt.so, there may
154 be missing functions. If ocaml-libvirt was compiled with
155 gcc, then these are turned into OCaml {!Libvirt.Not_supported}
158 We don't support libvirt < 0.2.1, and never will so don't ask us.
162 You can issue multiple concurrent libvirt requests in
163 different threads. However you must follow this rule:
164 Each thread must have its own separate libvirt connection, {i or}
165 you must implement your own mutex scheme to ensure that no
166 two threads can ever make concurrent calls using the same
169 (Note that multithreaded code is not well tested. If you find
170 bugs please report them.)
174 Libvirt requires all callers to call virInitialize before
175 using the library. This is done automatically for you by
176 these bindings when the program starts up, and we believe
177 that the way this is done is safe.
183 (** This is a "raw" UUID, ie. a packed string of bytes. *)
186 (** Type of XML (an uninterpreted string of bytes). Use PXP, expat,
187 xml-light, etc. if you want to do anything useful with the XML.
190 type filename = string
193 val get_version : ?driver:string -> unit -> int * int
194 (** [get_version ()] returns the library version in the first part
195 of the tuple, and [0] in the second part.
197 [get_version ~driver ()] returns the library version in the first
198 part of the tuple, and the version of the driver called [driver]
201 The version numbers are encoded as
202 1,000,000 * major + 1,000 * minor + release.
205 val uuid_length : int
206 (** Length of packed UUIDs. *)
208 val uuid_string_length : int
209 (** Length of UUID strings. *)
214 {{:http://caml.inria.fr/pub/ml-archives/caml-list/2004/07/80683af867cce6bf8fff273973f70c95.en.html}phantom types}
215 are used to ensure the type-safety of read-only
216 versus read-write connections.
218 All connection/domain/etc. objects are marked with
219 a phantom read-write or read-only type, and trying to
220 pass a read-only object into a function which could
221 mutate the object will cause a compile time error.
223 Each module provides a function like {!Libvirt.Connect.const}
224 to demote a read-write object into a read-only object. The
225 opposite operation is, of course, not allowed.
227 If you want to handle both read-write and read-only
228 connections at runtime, use a variant similar to this:
232 | Read_only of Libvirt.ro Libvirt.Connect.t
233 | Read_write of Libvirt.rw Libvirt.Connect.t
235 See also the source of [mlvirsh].
239 (** Forward definition of {!Job.t} to avoid recursive module dependencies. *)
241 (** {3 Connections} *)
246 (** Connection. Read-only connections have type [ro Connect.t] and
247 read-write connections have type [rw Connect.t].
251 model : string; (** CPU model *)
252 memory : int64; (** memory size in kilobytes *)
253 cpus : int; (** number of active CPUs *)
254 mhz : int; (** expected CPU frequency *)
255 nodes : int; (** number of NUMA nodes (1 = UMA) *)
256 sockets : int; (** number of CPU sockets per node *)
257 cores : int; (** number of cores per socket *)
258 threads : int; (** number of threads per core *)
261 val connect : ?name:string -> unit -> rw t
262 val connect_readonly : ?name:string -> unit -> ro t
263 (** [connect ~name ()] connects to the hypervisor with URI [name].
265 [connect ()] connects to the default hypervisor.
267 [connect_readonly] is the same but connects in read-only mode.
270 val close : [>`R] t -> unit
271 (** [close conn] closes and frees the connection object in memory.
273 The connection is automatically closed if it is garbage
274 collected. This function just forces it to be closed
275 and freed right away.
278 val get_type : [>`R] t -> string
279 (** Returns the name of the driver (hypervisor). *)
281 val get_version : [>`R] t -> int
282 (** Returns the driver version
283 [major * 1_000_000 + minor * 1000 + release]
285 val get_hostname : [>`R] t -> string
286 (** Returns the hostname of the physical server. *)
287 val get_uri : [>`R] t -> string
288 (** Returns the canonical connection URI. *)
289 val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
290 (** Returns the maximum number of virtual CPUs
291 supported by a guest VM of a particular type. *)
292 val list_domains : [>`R] t -> int -> int array
293 (** [list_domains conn max] returns the running domain IDs,
294 up to a maximum of [max] entries.
295 Call {!num_of_domains} first to get a value for [max].
297 val num_of_domains : [>`R] t -> int
298 (** Returns the number of running domains. *)
299 val get_capabilities : [>`R] t -> xml
300 (** Returns the hypervisor capabilities (as XML). *)
301 val num_of_defined_domains : [>`R] t -> int
302 (** Returns the number of inactive (shutdown) domains. *)
303 val list_defined_domains : [>`R] t -> int -> string array
304 (** [list_defined_domains conn max]
305 returns the names of the inactive domains, up to
306 a maximum of [max] entries.
307 Call {!num_of_defined_domains} first to get a value for [max].
309 val num_of_networks : [>`R] t -> int
310 (** Returns the number of networks. *)
311 val list_networks : [>`R] t -> int -> string array
312 (** [list_networks conn max]
313 returns the names of the networks, up to a maximum
315 Call {!num_of_networks} first to get a value for [max].
317 val num_of_defined_networks : [>`R] t -> int
318 (** Returns the number of inactive networks. *)
319 val list_defined_networks : [>`R] t -> int -> string array
320 (** [list_defined_networks conn max]
321 returns the names of the inactive networks, up to a maximum
323 Call {!num_of_defined_networks} first to get a value for [max].
326 val num_of_pools : [>`R] t -> int
327 (** Returns the number of storage pools. *)
328 val list_pools : [>`R] t -> int -> string array
329 (** Return list of storage pools. *)
330 val num_of_defined_pools : [>`R] t -> int
331 (** Returns the number of storage pools. *)
332 val list_defined_pools : [>`R] t -> int -> string array
333 (** Return list of storage pools. *)
335 (* The name of this function is inconsistent, but the inconsistency
336 * is really in libvirt itself.
338 val get_node_info : [>`R] t -> node_info
339 (** Return information about the physical server. *)
341 val node_get_free_memory : [> `R] t -> int64
343 [node_get_free_memory conn]
344 returns the amount of free memory (not allocated to any guest)
348 val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array
350 [node_get_cells_free_memory conn start max]
351 returns the amount of free memory on each NUMA cell in kilobytes.
352 [start] is the first cell for which we return free memory.
353 [max] is the maximum number of cells for which we return free memory.
354 Returns an array of up to [max] entries in length.
357 val maxcpus_of_node_info : node_info -> int
358 (** Calculate the total number of CPUs supported (but not necessarily
362 val cpumaplen : int -> int
363 (** Calculate the length (in bytes) required to store the complete
364 CPU map between a single virtual and all physical CPUs of a domain.
367 val use_cpu : string -> int -> unit
368 (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
369 val unuse_cpu : string -> int -> unit
370 (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
371 val cpu_usable : string -> int -> int -> int -> bool
372 (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
373 [cpu] is usable by [vcpu]. *)
375 external const : [>`R] t -> ro t = "%identity"
376 (** [const conn] turns a read/write connection into a read-only
377 connection. Note that the opposite operation is impossible.
380 (** Module dealing with connections. [Connect.t] is the
381 connection object. *)
388 (** Domain handle. Read-only handles have type [ro Domain.t] and
389 read-write handles have type [rw Domain.t].
393 | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
394 | InfoShutdown | InfoShutoff | InfoCrashed
397 state : state; (** running state *)
398 max_mem : int64; (** maximum memory in kilobytes *)
399 memory : int64; (** memory used in kilobytes *)
400 nr_virt_cpu : int; (** number of virtual CPUs *)
401 cpu_time : int64; (** CPU time used in nanoseconds *)
404 type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
407 number : int; (** virtual CPU number *)
408 vcpu_state : vcpu_state; (** state *)
409 vcpu_time : int64; (** CPU time used in nanoseconds *)
410 cpu : int; (** real CPU number, -1 if offline *)
413 type sched_param = string * sched_param_value
414 and sched_param_value =
415 | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
416 | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
417 | SchedFieldFloat of float | SchedFieldBool of bool
419 type migrate_flag = Live
421 type memory_flag = Virtual
431 type interface_stats = {
442 val create_linux : [>`W] Connect.t -> xml -> rw t
443 (** Create a new guest domain (not necessarily a Linux one)
446 val create_linux_job : [>`W] Connect.t -> xml -> ([`Domain], rw) job_t
447 (** Asynchronous domain creation. *)
448 val lookup_by_id : 'a Connect.t -> int -> 'a t
449 (** Lookup a domain by ID. *)
450 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
451 (** Lookup a domain by UUID. This uses the packed byte array UUID. *)
452 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
453 (** Lookup a domain by (string) UUID. *)
454 val lookup_by_name : 'a Connect.t -> string -> 'a t
455 (** Lookup a domain by name. *)
456 val destroy : [>`W] t -> unit
457 (** Abruptly destroy a domain. *)
458 val free : [>`R] t -> unit
459 (** [free domain] frees the domain object in memory.
461 The domain object is automatically freed if it is garbage
462 collected. This function just forces it to be freed right
466 val suspend : [>`W] t -> unit
467 (** Suspend a domain. *)
468 val resume : [>`W] t -> unit
469 (** Resume a domain. *)
470 val save : [>`W] t -> filename -> unit
471 (** Suspend a domain, then save it to the file. *)
472 val save_job : [>`W] t -> filename -> ([`Domain_nocreate], rw) job_t
473 (** Asynchronous domain suspend. *)
474 val restore : [>`W] Connect.t -> filename -> unit
475 (** Restore a domain from a file. *)
476 val restore_job : [>`W] Connect.t -> filename -> ([`Domain_nocreate], rw) job_t
477 (** Asynchronous domain restore. *)
478 val core_dump : [>`W] t -> filename -> unit
479 (** Force a domain to core dump to the named file. *)
480 val core_dump_job : [>`W] t -> filename -> ([`Domain_nocreate], rw) job_t
481 (** Asynchronous core dump. *)
482 val shutdown : [>`W] t -> unit
483 (** Shutdown a domain. *)
484 val reboot : [>`W] t -> unit
485 (** Reboot a domain. *)
486 val get_name : [>`R] t -> string
487 (** Get the domain name. *)
488 val get_uuid : [>`R] t -> uuid
489 (** Get the domain UUID (as a packed byte array). *)
490 val get_uuid_string : [>`R] t -> string
491 (** Get the domain UUID (as a printable string). *)
492 val get_id : [>`R] t -> int
493 (** [getid dom] returns the ID of the domain.
495 Do not call this on a defined but not running domain. Those
496 domains don't have IDs, and you'll get an error here.
499 val get_os_type : [>`R] t -> string
500 (** Get the operating system type. *)
501 val get_max_memory : [>`R] t -> int64
502 (** Get the maximum memory allocation. *)
503 val set_max_memory : [>`W] t -> int64 -> unit
504 (** Set the maximum memory allocation. *)
505 val set_memory : [>`W] t -> int64 -> unit
506 (** Set the normal memory allocation. *)
507 val get_info : [>`R] t -> info
508 (** Get information about a domain. *)
509 val get_xml_desc : [>`R] t -> xml
510 (** Get the XML description of a domain. *)
511 val get_scheduler_type : [>`R] t -> string * int
512 (** Get the scheduler type. *)
513 val get_scheduler_parameters : [>`R] t -> int -> sched_param array
514 (** Get the array of scheduler parameters. *)
515 val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
516 (** Set the array of scheduler parameters. *)
517 val define_xml : [>`W] Connect.t -> xml -> rw t
518 (** Define a new domain (but don't start it up) from the XML. *)
519 val undefine : [>`W] t -> unit
520 (** Undefine a domain - removes its configuration. *)
521 val create : [>`W] t -> unit
522 (** Launch a defined (inactive) domain. *)
523 val create_job : [>`W] t -> ([`Domain_nocreate], rw) job_t
524 (** Asynchronous launch domain. *)
525 val get_autostart : [>`R] t -> bool
526 (** Get the autostart flag for a domain. *)
527 val set_autostart : [>`W] t -> bool -> unit
528 (** Set the autostart flag for a domain. *)
529 val set_vcpus : [>`W] t -> int -> unit
530 (** Change the number of vCPUs available to a domain. *)
531 val pin_vcpu : [>`W] t -> int -> string -> unit
532 (** [pin_vcpu dom vcpu bitmap] pins a domain vCPU to a bitmap of physical
533 CPUs. See the libvirt documentation for details of the
534 layout of the bitmap. *)
535 val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
536 (** [get_vcpus dom maxinfo maplen] returns the pinning information
537 for a domain. See the libvirt documentation for details
538 of the array and bitmap returned from this function.
540 val get_max_vcpus : [>`R] t -> int
541 (** Returns the maximum number of vCPUs supported for this domain. *)
542 val attach_device : [>`W] t -> xml -> unit
543 (** Attach a device (described by the device XML) to a domain. *)
544 val detach_device : [>`W] t -> xml -> unit
545 (** Detach a device (described by the device XML) from a domain. *)
547 val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
548 ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
549 (** [migrate dom dconn flags ()] migrates a domain to a
550 destination host described by [dconn].
552 The optional flag [?dname] is used to rename the domain.
554 The optional flag [?uri] is used to route the migration.
556 The optional flag [?bandwidth] is used to limit the bandwidth
557 used for migration (in Mbps). *)
559 val block_stats : [>`R] t -> string -> block_stats
560 (** Returns block device stats. *)
561 val interface_stats : [>`R] t -> string -> interface_stats
562 (** Returns network interface stats. *)
564 val block_peek : [>`R] t -> string -> int64 -> int -> string -> int -> unit
565 (** [block_peek dom path offset size buf boff] reads [size] bytes at
566 [offset] in the domain's [path] block device.
568 If successful then the data is written into [buf] starting
569 at offset [boff], for [size] bytes. *)
570 val memory_peek : [>`R] t -> memory_flag list -> int64 -> int ->
571 string -> int -> unit
572 (** [memory_peek dom Virtual offset size] reads [size] bytes
573 at [offset] in the domain's virtual memory.
575 If successful then the data is written into [buf] starting
576 at offset [boff], for [size] bytes. *)
578 external const : [>`R] t -> ro t = "%identity"
579 (** [const dom] turns a read/write domain handle into a read-only
580 domain handle. Note that the opposite operation is impossible.
583 (** Module dealing with domains. [Domain.t] is the
591 (** Network handle. Read-only handles have type [ro Network.t] and
592 read-write handles have type [rw Network.t].
595 val lookup_by_name : 'a Connect.t -> string -> 'a t
596 (** Lookup a network by name. *)
597 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
598 (** Lookup a network by (packed) UUID. *)
599 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
600 (** Lookup a network by UUID string. *)
601 val create_xml : [>`W] Connect.t -> xml -> rw t
602 (** Create a network. *)
603 val create_xml_job : [>`W] Connect.t -> xml -> ([`Network], rw) job_t
604 (** Asynchronous create network. *)
605 val define_xml : [>`W] Connect.t -> xml -> rw t
606 (** Define but don't activate a network. *)
607 val undefine : [>`W] t -> unit
608 (** Undefine configuration of a network. *)
609 val create : [>`W] t -> unit
610 (** Start up a defined (inactive) network. *)
611 val create_job : [>`W] t -> ([`Network_nocreate], rw) job_t
612 (** Asynchronous start network. *)
613 val destroy : [>`W] t -> unit
614 (** Destroy a network. *)
615 val free : [>`R] t -> unit
616 (** [free network] frees the network object in memory.
618 The network object is automatically freed if it is garbage
619 collected. This function just forces it to be freed right
623 val get_name : [>`R] t -> string
624 (** Get network name. *)
625 val get_uuid : [>`R] t -> uuid
626 (** Get network packed UUID. *)
627 val get_uuid_string : [>`R] t -> string
628 (** Get network UUID as a printable string. *)
629 val get_xml_desc : [>`R] t -> xml
630 (** Get XML description of a network. *)
631 val get_bridge_name : [>`R] t -> string
632 (** Get bridge device name of a network. *)
633 val get_autostart : [>`R] t -> bool
634 (** Get the autostart flag for a network. *)
635 val set_autostart : [>`W] t -> bool -> unit
636 (** Set the autostart flag for a network. *)
638 external const : [>`R] t -> ro t = "%identity"
639 (** [const network] turns a read/write network handle into a read-only
640 network handle. Note that the opposite operation is impossible.
643 (** Module dealing with networks. [Network.t] is the
646 (** {3 Storage pools} *)
651 (** Storage pool handle. *)
653 type pool_state = Inactive | Building | Running | Degraded
654 (** State of the storage pool. *)
656 type pool_build_flags = New | Repair | Resize
657 (** Flags for creating a storage pool. *)
659 type pool_delete_flags = Normal | Zeroed
660 (** Flags for deleting a storage pool. *)
663 state : pool_state; (** Pool state. *)
664 capacity : int64; (** Logical size in bytes. *)
665 allocation : int64; (** Currently allocated in bytes. *)
666 available : int64; (** Remaining free space bytes. *)
669 val lookup_by_name : 'a Connect.t -> string -> 'a t
670 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
671 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
672 (** Look up a storage pool by name, UUID or UUID string. *)
674 val create_xml : [>`W] Connect.t -> xml -> rw t
675 (** Create a storage pool. *)
676 val define_xml : [>`W] Connect.t -> xml -> rw t
677 (** Define but don't activate a storage pool. *)
678 val build : [>`W] t -> pool_build_flags -> unit
679 (** Build a storage pool. *)
680 val undefine : [>`W] t -> unit
681 (** Undefine configuration of a storage pool. *)
682 val create : [>`W] t -> unit
683 (** Start up a defined (inactive) storage pool. *)
684 val destroy : [>`W] t -> unit
685 (** Destroy a storage pool. *)
686 val delete : [>`W] t -> unit
687 (** Delete a storage pool. *)
688 val free : [>`R] t -> unit
689 (** Free a storage pool object in memory.
691 The storage pool object is automatically freed if it is garbage
692 collected. This function just forces it to be freed right
695 val refresh : [`R] t -> unit
696 (** Refresh the list of volumes in the storage pool. *)
698 val get_name : [`R] t -> string
699 (** Name of the pool. *)
700 val get_uuid : [`R] t -> uuid
701 (** Get the UUID (as a packed byte array). *)
702 val get_uuid_string : [`R] t -> string
703 (** Get the UUID (as a printable string). *)
704 val get_info : [`R] t -> pool_info
705 (** Get information about the pool. *)
706 val get_xml_desc : [`R] t -> xml
707 (** Get the XML description. *)
708 val get_autostart : [`R] t -> bool
709 (** Get the autostart flag for the storage pool. *)
710 val set_autostart : [`W] t -> bool -> unit
711 (** Set the autostart flag for the storage pool. *)
713 val num_of_volumes : [`R] t -> int
714 (** Returns the number of storage volumes within the storage pool. *)
715 val list_volumes : [`R] t -> int -> string array
716 (** Return list of storage volumes. *)
718 external const : [>`R] t -> ro t = "%identity"
719 (** [const conn] turns a read/write storage pool into a read-only
720 pool. Note that the opposite operation is impossible.
723 (** Module dealing with storage pools. *)
725 (** {3 Storage volumes} *)
730 (** Storage volume handle. *)
732 type vol_type = File | Block
733 (** Type of a storage volume. *)
735 type vol_delete_flags = Normal | Zeroed
736 (** Flags for deleting a storage volume. *)
739 typ : vol_type; (** Type of storage volume. *)
740 capacity : int64; (** Logical size in bytes. *)
741 allocation : int64; (** Currently allocated in bytes. *)
744 val lookup_by_name : 'a Pool.t -> string -> 'a t
745 val lookup_by_key : 'a Connect.t -> string -> 'a t
746 val lookup_by_path : 'a Connect.t -> string -> 'a t
747 (** Look up a storage volume by name, key or path volume. *)
749 val pool_of_volume : 'a t -> 'a Pool.t
750 (** Get the storage pool containing this volume. *)
752 val get_name : [`R] t -> string
753 (** Name of the volume. *)
754 val get_key : [`R] t -> string
755 (** Key of the volume. *)
756 val get_path : [`R] t -> string
757 (** Path of the volume. *)
758 val get_info : [`R] t -> vol_info
759 (** Get information about the storage volume. *)
760 val get_xml_desc : [`R] t -> xml
761 (** Get the XML description. *)
763 val create_xml : [`W] Pool.t -> xml -> unit
764 (** Create a storage volume. *)
765 val delete : [`W] t -> unit
766 (** Delete a storage volume. *)
767 val free : [>`R] t -> unit
768 (** Free a storage volume object in memory.
770 The storage volume object is automatically freed if it is garbage
771 collected. This function just forces it to be freed right
775 external const : [>`R] t -> ro t = "%identity"
776 (** [const conn] turns a read/write storage volume into a read-only
777 volume. Note that the opposite operation is impossible.
780 (** Module dealing with storage volumes. *)
782 (** {3 Jobs and asynchronous processing} *)
786 type ('jobclass, 'rw) t = ('jobclass, 'rw) job_t
787 (** A background asynchronous job.
789 Jobs represent a pending operation such as domain creation.
790 The possible types for a job are:
793 (`Domain, `W) Job.t Job creating a new domain
794 (`Domain_nocreate, `W) Job.t Job acting on an existing domain
795 (`Network, `W) Job.t Job creating a new network
796 (`Network_nocreate, `W) Job.t Job acting on an existing network
800 type job_type = Bounded | Unbounded
801 (** A Bounded job is one where we can estimate time to completion. *)
803 type job_state = Running | Complete | Failed | Cancelled
804 (** State of the job. *)
807 typ : job_type; (** Job type (Bounded, Unbounded) *)
808 state : job_state; (** Job state (Running, etc.) *)
809 running_time : int; (** Actual running time (seconds) *)
810 (** The following fields are only available in Bounded jobs: *)
811 remaining_time : int; (** Estimated time left (seconds) *)
812 percent_complete : int (** Estimated percent complete *)
815 val get_info : ('a,'b) t -> job_info
816 (** Get information and status about the job. *)
818 val get_domain : ([`Domain], 'a) t -> 'a Domain.t
819 (** Get the completed domain from a job.
821 You should only call it on a job in state Complete. *)
823 val get_network : ([`Network], 'a) t -> 'a Network.t
824 (** Get the completed network from a job.
826 You should only call it on a job in state Complete. *)
828 val cancel : ('a,'b) t -> unit
831 val free : ('a, [>`R]) t -> unit
832 (** Free a job object in memory.
834 The job object is automatically freed if it is garbage
835 collected. This function just forces it to be freed right
839 external const : ('a, [>`R]) t -> ('a, ro) t = "%identity"
840 (** [const conn] turns a read/write job into a read-only
841 job. Note that the opposite operation is impossible.
844 (** Module dealing with asynchronous jobs. *)
846 (** {3 Error handling and exceptions} *)
852 | VIR_ERR_INTERNAL_ERROR
855 | VIR_ERR_UNKNOWN_HOST
857 | VIR_ERR_INVALID_CONN
858 | VIR_ERR_INVALID_DOMAIN
859 | VIR_ERR_INVALID_ARG
860 | VIR_ERR_OPERATION_FAILED
862 | VIR_ERR_POST_FAILED
864 | VIR_ERR_SEXPR_SERIAL
875 | VIR_ERR_NO_XENSTORE
876 | VIR_ERR_DRIVER_FULL
877 | VIR_ERR_CALL_FAILED
880 | VIR_ERR_OPERATION_DENIED
881 | VIR_ERR_OPEN_FAILED
882 | VIR_ERR_READ_FAILED
883 | VIR_ERR_PARSE_FAILED
884 | VIR_ERR_CONF_SYNTAX
885 | VIR_ERR_WRITE_FAILED
887 | VIR_ERR_INVALID_NETWORK
888 | VIR_ERR_NETWORK_EXIST
889 | VIR_ERR_SYSTEM_ERROR
891 | VIR_ERR_GNUTLS_ERROR
895 | VIR_ERR_INVALID_MAC
896 | VIR_ERR_AUTH_FAILED
897 | VIR_ERR_INVALID_STORAGE_POOL
898 | VIR_ERR_INVALID_STORAGE_VOL
900 | VIR_ERR_NO_STORAGE_POOL
901 | VIR_ERR_NO_STORAGE_VOL
902 (* ^^ NB: If you add a variant you MUST edit
903 libvirt_c_epilogue.c:MAX_VIR_* *)
904 | VIR_ERR_UNKNOWN of int
905 (** See [<libvirt/virterror.h>] for meaning of these codes. *)
907 val string_of_code : code -> string
926 | VIR_FROM_STATS_LINUX
928 (* ^^ NB: If you add a variant you MUST edit
929 libvirt_c_epilogue.c: MAX_VIR_* *)
930 | VIR_FROM_UNKNOWN of int
931 (** Subsystem / driver which produced the error. *)
933 val string_of_domain : domain -> string
939 (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *)
940 | VIR_ERR_UNKNOWN_LEVEL of int
941 (** No error, a warning or an error. *)
943 val string_of_level : level -> string
946 code : code; (** Error code. *)
947 domain : domain; (** Origin of the error. *)
948 message : string option; (** Human-readable message. *)
949 level : level; (** Error or warning. *)
950 str1 : string option; (** Informational string. *)
951 str2 : string option; (** Informational string. *)
952 str3 : string option; (** Informational string. *)
953 int1 : int32; (** Informational integer. *)
954 int2 : int32; (** Informational integer. *)
956 (** An error object. *)
958 val to_string : t -> string
959 (** Turn the exception into a printable string. *)
961 val get_last_error : unit -> t option
962 val get_last_conn_error : [>`R] Connect.t -> t option
963 (** Get the last error at a global or connection level.
965 Normally you do not need to use these functions because
966 the library automatically turns errors into exceptions.
969 val reset_last_error : unit -> unit
970 val reset_last_conn_error : [>`R] Connect.t -> unit
971 (** Reset the error at a global or connection level.
973 Normally you do not need to use these functions.
976 val no_error : unit -> t
977 (** Creates an empty error message.
979 Normally you do not need to use this function.
982 (** Module dealing with errors. *)
984 exception Virterror of Virterror.t
985 (** This exception can be raised by any library function that detects
986 an error. To get a printable error message, call
987 {!Virterror.to_string} on the content of this exception.
990 exception Not_supported of string
993 [Not_supported "virFoo"]
994 (where [virFoo] is the libvirt function name) if a function is
995 not supported at either compile or run time. This applies to
996 any libvirt function added after version 0.2.1.
998 See also {{:http://libvirt.org/hvsupport.html}http://libvirt.org/hvsupport.html}