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 Please see the file ../COPYING.LIB.
19 {2 Introduction and examples}
21 This is a set of bindings for writing OCaml programs to
22 manage virtual machines through {{:http://libvirt.org/}libvirt}.
24 {3 Using libvirt interactively}
26 Using the interactive toplevel:
30 Objective Caml version 3.10.0
33 # #load "mllibvirt.cma";;
34 # let name = "test:///default";;
35 val name : string = "test:///default"
36 # let conn = Libvirt.Connect.connect_readonly ~name () ;;
37 val conn : Libvirt.ro Libvirt.Connect.t = <abstr>
38 # Libvirt.Connect.get_node_info conn;;
39 : Libvirt.Connect.node_info =
40 {Libvirt.Connect.model = "i686"; Libvirt.Connect.memory = 3145728L;
41 Libvirt.Connect.cpus = 16; Libvirt.Connect.mhz = 1400;
42 Libvirt.Connect.nodes = 2; Libvirt.Connect.sockets = 2;
43 Libvirt.Connect.cores = 2; Libvirt.Connect.threads = 2}
46 {3 Compiling libvirt programs}
48 This command compiles a program to native code:
51 ocamlopt -I +libvirt mllibvirt.cmxa list_domains.ml -o list_domains
54 {3 Example: Connect to the hypervisor}
56 The main modules are {!Libvirt.Connect}, {!Libvirt.Domain} and
57 {!Libvirt.Network} corresponding respectively to the
58 {{:http://libvirt.org/html/libvirt-libvirt.html}virConnect*, virDomain* and virNetwork* functions from libvirt}.
59 For brevity I usually rename these modules like this:
62 module C = Libvirt.Connect
63 module D = Libvirt.Domain
64 module N = Libvirt.Network
67 To get a connection handle, assuming a Xen hypervisor:
71 let conn = C.connect_readonly ~name ()
74 {3 Example: List running domains}
79 let n = C.num_of_domains conn in
80 let ids = C.list_domains conn n in
81 let domains = Array.map (D.lookup_by_id conn) ids in
84 printf "%8d %s\n%!" (D.get_id dom) (D.get_name dom)
88 {3 Example: List inactive domains}
91 let n = C.num_of_defined_domains conn in
92 let names = C.list_defined_domains conn n in
95 printf "inactive %s\n%!" name
99 {3 Example: Print node info}
102 let node_info = C.get_node_info conn in
103 printf "model = %s\n" node_info.C.model;
104 printf "memory = %Ld K\n" node_info.C.memory;
105 printf "cpus = %d\n" node_info.C.cpus;
106 printf "mhz = %d\n" node_info.C.mhz;
107 printf "nodes = %d\n" node_info.C.nodes;
108 printf "sockets = %d\n" node_info.C.sockets;
109 printf "cores = %d\n" node_info.C.cores;
110 printf "threads = %d\n%!" node_info.C.threads;
112 let hostname = C.get_hostname conn in
113 printf "hostname = %s\n%!" hostname;
115 let uri = C.get_uri conn in
116 printf "uri = %s\n%!" uri
122 (** {2 Programming issues}
124 {3 General safety issues}
126 Memory allocation / automatic garbage collection of all libvirt
127 objects should be completely safe. If you find any safety issues
128 or if your pure OCaml program ever segfaults, please contact the author.
130 You can force a libvirt object to be freed early by calling
131 the [close] function on the object. This shouldn't affect
132 the safety of garbage collection and should only be used when
133 you want to explicitly free memory. Note that explicitly
134 closing a connection object does nothing if there are still
135 unclosed domain or network objects referencing it.
137 Note that even though you hold open (eg) a domain object, that
138 doesn't mean that the domain (virtual machine) actually exists.
139 The domain could have been shut down or deleted by another user.
140 Thus domain objects can through odd exceptions at any time.
141 This is just the nature of virtualisation.
143 {3 Backwards and forwards compatibility}
145 OCaml-libvirt is backwards and forwards compatible with
146 any libvirt >= 0.2.1. One consequence of this is that
147 your program can dynamically link to a {i newer} version of
148 libvirt than it was compiled with, and it should still
151 When we link to an older version of libvirt.so, there may
152 be missing functions. If ocaml-libvirt was compiled with
153 gcc, then these are turned into OCaml {!Libvirt.Not_supported}
156 We don't support libvirt < 0.2.1, and never will so don't ask us.
160 You can issue multiple concurrent libvirt requests in
161 different threads. However you must follow this rule:
162 Each thread must have its own separate libvirt connection, {i or}
163 you must implement your own mutex scheme to ensure that no
164 two threads can ever make concurrent calls using the same
167 (Note that multithreaded code is not well tested. If you find
168 bugs please report them.)
172 Libvirt requires all callers to call virInitialize before
173 using the library. This is done automatically for you by
174 these bindings when the program starts up, and we believe
175 that the way this is done is safe.
181 (** This is a "raw" UUID, ie. a packed string of bytes. *)
184 (** Type of XML (an uninterpreted string of bytes). Use PXP, expat,
185 xml-light, etc. if you want to do anything useful with the XML.
188 type filename = string
191 val get_version : ?driver:string -> unit -> int * int
192 (** [get_version ()] returns the library version in the first part
193 of the tuple, and [0] in the second part.
195 [get_version ~driver ()] returns the library version in the first
196 part of the tuple, and the version of the driver called [driver]
199 The version numbers are encoded as
200 1,000,000 * major + 1,000 * minor + release.
203 val uuid_length : int
204 (** Length of packed UUIDs. *)
206 val uuid_string_length : int
207 (** Length of UUID strings. *)
212 {{:http://caml.inria.fr/pub/ml-archives/caml-list/2004/07/80683af867cce6bf8fff273973f70c95.en.html}phantom types}
213 are used to ensure the type-safety of read-only
214 versus read-write connections.
216 All connection/domain/etc. objects are marked with
217 a phantom read-write or read-only type, and trying to
218 pass a read-only object into a function which could
219 mutate the object will cause a compile time error.
221 Each module provides a function like {!Libvirt.Connect.const}
222 to demote a read-write object into a read-only object. The
223 opposite operation is, of course, not allowed.
225 If you want to handle both read-write and read-only
226 connections at runtime, use a variant similar to this:
230 | Read_only of Libvirt.ro Libvirt.Connect.t
231 | Read_write of Libvirt.rw Libvirt.Connect.t
233 See also the source of [mlvirsh].
237 (** Forward definition of {!Job.t} to avoid recursive module dependencies. *)
239 (** {3 Connections} *)
244 (** Connection. Read-only connections have type [ro Connect.t] and
245 read-write connections have type [rw Connect.t].
249 model : string; (** CPU model *)
250 memory : int64; (** memory size in kilobytes *)
251 cpus : int; (** number of active CPUs *)
252 mhz : int; (** expected CPU frequency *)
253 nodes : int; (** number of NUMA nodes (1 = UMA) *)
254 sockets : int; (** number of CPU sockets per node *)
255 cores : int; (** number of cores per socket *)
256 threads : int; (** number of threads per core *)
259 val connect : ?name:string -> unit -> rw t
260 val connect_readonly : ?name:string -> unit -> ro t
261 (** [connect ~name ()] connects to the hypervisor with URI [name].
263 [connect ()] connects to the default hypervisor.
265 [connect_readonly] is the same but connects in read-only mode.
268 val close : [>`R] t -> unit
269 (** [close conn] closes and frees the connection object in memory.
271 The connection is automatically closed if it is garbage
272 collected. This function just forces it to be closed
273 and freed right away.
276 val get_type : [>`R] t -> string
277 (** Returns the name of the driver (hypervisor). *)
279 val get_version : [>`R] t -> int
280 (** Returns the driver version
281 [major * 1_000_000 + minor * 1000 + release]
283 val get_hostname : [>`R] t -> string
284 (** Returns the hostname of the physical server. *)
285 val get_uri : [>`R] t -> string
286 (** Returns the canonical connection URI. *)
287 val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
288 (** Returns the maximum number of virtual CPUs
289 supported by a guest VM of a particular type. *)
290 val list_domains : [>`R] t -> int -> int array
291 (** [list_domains conn max] returns the running domain IDs,
292 up to a maximum of [max] entries.
293 Call {!num_of_domains} first to get a value for [max].
295 val num_of_domains : [>`R] t -> int
296 (** Returns the number of running domains. *)
297 val get_capabilities : [>`R] t -> xml
298 (** Returns the hypervisor capabilities (as XML). *)
299 val num_of_defined_domains : [>`R] t -> int
300 (** Returns the number of inactive (shutdown) domains. *)
301 val list_defined_domains : [>`R] t -> int -> string array
302 (** [list_defined_domains conn max]
303 returns the names of the inactive domains, up to
304 a maximum of [max] entries.
305 Call {!num_of_defined_domains} first to get a value for [max].
307 val num_of_networks : [>`R] t -> int
308 (** Returns the number of networks. *)
309 val list_networks : [>`R] t -> int -> string array
310 (** [list_networks conn max]
311 returns the names of the networks, up to a maximum
313 Call {!num_of_networks} first to get a value for [max].
315 val num_of_defined_networks : [>`R] t -> int
316 (** Returns the number of inactive networks. *)
317 val list_defined_networks : [>`R] t -> int -> string array
318 (** [list_defined_networks conn max]
319 returns the names of the inactive networks, up to a maximum
321 Call {!num_of_defined_networks} first to get a value for [max].
324 val num_of_pools : [>`R] t -> int
325 (** Returns the number of storage pools. *)
326 val list_pools : [>`R] t -> int -> string array
327 (** Return list of storage pools. *)
328 val num_of_defined_pools : [>`R] t -> int
329 (** Returns the number of storage pools. *)
330 val list_defined_pools : [>`R] t -> int -> string array
331 (** Return list of storage pools. *)
333 (* The name of this function is inconsistent, but the inconsistency
334 * is really in libvirt itself.
336 val get_node_info : [>`R] t -> node_info
337 (** Return information about the physical server. *)
339 val node_get_free_memory : [> `R] t -> int64
341 [node_get_free_memory conn]
342 returns the amount of free memory (not allocated to any guest)
346 val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array
348 [node_get_cells_free_memory conn start max]
349 returns the amount of free memory on each NUMA cell in kilobytes.
350 [start] is the first cell for which we return free memory.
351 [max] is the maximum number of cells for which we return free memory.
352 Returns an array of up to [max] entries in length.
355 val maxcpus_of_node_info : node_info -> int
356 (** Calculate the total number of CPUs supported (but not necessarily
360 val cpumaplen : int -> int
361 (** Calculate the length (in bytes) required to store the complete
362 CPU map between a single virtual and all physical CPUs of a domain.
365 val use_cpu : string -> int -> unit
366 (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
367 val unuse_cpu : string -> int -> unit
368 (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
369 val cpu_usable : string -> int -> int -> int -> bool
370 (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
371 [cpu] is usable by [vcpu]. *)
373 external const : [>`R] t -> ro t = "%identity"
374 (** [const conn] turns a read/write connection into a read-only
375 connection. Note that the opposite operation is impossible.
378 (** Module dealing with connections. [Connect.t] is the
379 connection object. *)
386 (** Domain handle. Read-only handles have type [ro Domain.t] and
387 read-write handles have type [rw Domain.t].
391 | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
392 | InfoShutdown | InfoShutoff | InfoCrashed
395 state : state; (** running state *)
396 max_mem : int64; (** maximum memory in kilobytes *)
397 memory : int64; (** memory used in kilobytes *)
398 nr_virt_cpu : int; (** number of virtual CPUs *)
399 cpu_time : int64; (** CPU time used in nanoseconds *)
402 type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
405 number : int; (** virtual CPU number *)
406 vcpu_state : vcpu_state; (** state *)
407 vcpu_time : int64; (** CPU time used in nanoseconds *)
408 cpu : int; (** real CPU number, -1 if offline *)
411 type sched_param = string * sched_param_value
412 and sched_param_value =
413 | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
414 | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
415 | SchedFieldFloat of float | SchedFieldBool of bool
417 type migrate_flag = Live
419 type memory_flag = Virtual
429 type interface_stats = {
440 val create_linux : [>`W] Connect.t -> xml -> rw t
441 (** Create a new guest domain (not necessarily a Linux one)
444 val create_linux_job : [>`W] Connect.t -> xml -> ([`Domain], rw) job_t
445 (** Asynchronous domain creation. *)
446 val lookup_by_id : 'a Connect.t -> int -> 'a t
447 (** Lookup a domain by ID. *)
448 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
449 (** Lookup a domain by UUID. This uses the packed byte array UUID. *)
450 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
451 (** Lookup a domain by (string) UUID. *)
452 val lookup_by_name : 'a Connect.t -> string -> 'a t
453 (** Lookup a domain by name. *)
454 val destroy : [>`W] t -> unit
455 (** Abruptly destroy a domain. *)
456 val free : [>`R] t -> unit
457 (** [free domain] frees the domain object in memory.
459 The domain object is automatically freed if it is garbage
460 collected. This function just forces it to be freed right
464 val suspend : [>`W] t -> unit
465 (** Suspend a domain. *)
466 val resume : [>`W] t -> unit
467 (** Resume a domain. *)
468 val save : [>`W] t -> filename -> unit
469 (** Suspend a domain, then save it to the file. *)
470 val save_job : [>`W] t -> filename -> ([`Domain_nocreate], rw) job_t
471 (** Asynchronous domain suspend. *)
472 val restore : [>`W] Connect.t -> filename -> unit
473 (** Restore a domain from a file. *)
474 val restore_job : [>`W] Connect.t -> filename -> ([`Domain_nocreate], rw) job_t
475 (** Asynchronous domain restore. *)
476 val core_dump : [>`W] t -> filename -> unit
477 (** Force a domain to core dump to the named file. *)
478 val core_dump_job : [>`W] t -> filename -> ([`Domain_nocreate], rw) job_t
479 (** Asynchronous core dump. *)
480 val shutdown : [>`W] t -> unit
481 (** Shutdown a domain. *)
482 val reboot : [>`W] t -> unit
483 (** Reboot a domain. *)
484 val get_name : [>`R] t -> string
485 (** Get the domain name. *)
486 val get_uuid : [>`R] t -> uuid
487 (** Get the domain UUID (as a packed byte array). *)
488 val get_uuid_string : [>`R] t -> string
489 (** Get the domain UUID (as a printable string). *)
490 val get_id : [>`R] t -> int
491 (** [getid dom] returns the ID of the domain.
493 Do not call this on a defined but not running domain. Those
494 domains don't have IDs, and you'll get an error here.
497 val get_os_type : [>`R] t -> string
498 (** Get the operating system type. *)
499 val get_max_memory : [>`R] t -> int64
500 (** Get the maximum memory allocation. *)
501 val set_max_memory : [>`W] t -> int64 -> unit
502 (** Set the maximum memory allocation. *)
503 val set_memory : [>`W] t -> int64 -> unit
504 (** Set the normal memory allocation. *)
505 val get_info : [>`R] t -> info
506 (** Get information about a domain. *)
507 val get_xml_desc : [>`R] t -> xml
508 (** Get the XML description of a domain. *)
509 val get_scheduler_type : [>`R] t -> string * int
510 (** Get the scheduler type. *)
511 val get_scheduler_parameters : [>`R] t -> int -> sched_param array
512 (** Get the array of scheduler parameters. *)
513 val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
514 (** Set the array of scheduler parameters. *)
515 val define_xml : [>`W] Connect.t -> xml -> rw t
516 (** Define a new domain (but don't start it up) from the XML. *)
517 val undefine : [>`W] t -> unit
518 (** Undefine a domain - removes its configuration. *)
519 val create : [>`W] t -> unit
520 (** Launch a defined (inactive) domain. *)
521 val create_job : [>`W] t -> ([`Domain_nocreate], rw) job_t
522 (** Asynchronous launch domain. *)
523 val get_autostart : [>`R] t -> bool
524 (** Get the autostart flag for a domain. *)
525 val set_autostart : [>`W] t -> bool -> unit
526 (** Set the autostart flag for a domain. *)
527 val set_vcpus : [>`W] t -> int -> unit
528 (** Change the number of vCPUs available to a domain. *)
529 val pin_vcpu : [>`W] t -> int -> string -> unit
530 (** [pin_vcpu dom vcpu bitmap] pins a domain vCPU to a bitmap of physical
531 CPUs. See the libvirt documentation for details of the
532 layout of the bitmap. *)
533 val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
534 (** [get_vcpus dom maxinfo maplen] returns the pinning information
535 for a domain. See the libvirt documentation for details
536 of the array and bitmap returned from this function.
538 val get_max_vcpus : [>`R] t -> int
539 (** Returns the maximum number of vCPUs supported for this domain. *)
540 val attach_device : [>`W] t -> xml -> unit
541 (** Attach a device (described by the device XML) to a domain. *)
542 val detach_device : [>`W] t -> xml -> unit
543 (** Detach a device (described by the device XML) from a domain. *)
545 val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
546 ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
547 (** [migrate dom dconn flags ()] migrates a domain to a
548 destination host described by [dconn].
550 The optional flag [?dname] is used to rename the domain.
552 The optional flag [?uri] is used to route the migration.
554 The optional flag [?bandwidth] is used to limit the bandwidth
555 used for migration (in Mbps). *)
557 val block_stats : [>`R] t -> string -> block_stats
558 (** Returns block device stats. *)
559 val interface_stats : [>`R] t -> string -> interface_stats
560 (** Returns network interface stats. *)
562 val block_peek : [>`R] t -> string -> int64 -> int -> string -> int -> unit
563 (** [block_peek dom path offset size buf boff] reads [size] bytes at
564 [offset] in the domain's [path] block device.
566 If successful then the data is written into [buf] starting
567 at offset [boff], for [size] bytes. *)
568 val memory_peek : [>`R] t -> memory_flag list -> int64 -> int ->
569 string -> int -> unit
570 (** [memory_peek dom Virtual offset size] reads [size] bytes
571 at [offset] in the domain's virtual memory.
573 If successful then the data is written into [buf] starting
574 at offset [boff], for [size] bytes. *)
576 external const : [>`R] t -> ro t = "%identity"
577 (** [const dom] turns a read/write domain handle into a read-only
578 domain handle. Note that the opposite operation is impossible.
581 (** Module dealing with domains. [Domain.t] is the
589 (** Network handle. Read-only handles have type [ro Network.t] and
590 read-write handles have type [rw Network.t].
593 val lookup_by_name : 'a Connect.t -> string -> 'a t
594 (** Lookup a network by name. *)
595 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
596 (** Lookup a network by (packed) UUID. *)
597 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
598 (** Lookup a network by UUID string. *)
599 val create_xml : [>`W] Connect.t -> xml -> rw t
600 (** Create a network. *)
601 val create_xml_job : [>`W] Connect.t -> xml -> ([`Network], rw) job_t
602 (** Asynchronous create network. *)
603 val define_xml : [>`W] Connect.t -> xml -> rw t
604 (** Define but don't activate a network. *)
605 val undefine : [>`W] t -> unit
606 (** Undefine configuration of a network. *)
607 val create : [>`W] t -> unit
608 (** Start up a defined (inactive) network. *)
609 val create_job : [>`W] t -> ([`Network_nocreate], rw) job_t
610 (** Asynchronous start network. *)
611 val destroy : [>`W] t -> unit
612 (** Destroy a network. *)
613 val free : [>`R] t -> unit
614 (** [free network] frees the network object in memory.
616 The network object is automatically freed if it is garbage
617 collected. This function just forces it to be freed right
621 val get_name : [>`R] t -> string
622 (** Get network name. *)
623 val get_uuid : [>`R] t -> uuid
624 (** Get network packed UUID. *)
625 val get_uuid_string : [>`R] t -> string
626 (** Get network UUID as a printable string. *)
627 val get_xml_desc : [>`R] t -> xml
628 (** Get XML description of a network. *)
629 val get_bridge_name : [>`R] t -> string
630 (** Get bridge device name of a network. *)
631 val get_autostart : [>`R] t -> bool
632 (** Get the autostart flag for a network. *)
633 val set_autostart : [>`W] t -> bool -> unit
634 (** Set the autostart flag for a network. *)
636 external const : [>`R] t -> ro t = "%identity"
637 (** [const network] turns a read/write network handle into a read-only
638 network handle. Note that the opposite operation is impossible.
641 (** Module dealing with networks. [Network.t] is the
644 (** {3 Storage pools} *)
649 (** Storage pool handle. *)
651 type pool_state = Inactive | Building | Running | Degraded
652 (** State of the storage pool. *)
654 type pool_build_flags = New | Repair | Resize
655 (** Flags for creating a storage pool. *)
657 type pool_delete_flags = Normal | Zeroed
658 (** Flags for deleting a storage pool. *)
661 state : pool_state; (** Pool state. *)
662 capacity : int64; (** Logical size in bytes. *)
663 allocation : int64; (** Currently allocated in bytes. *)
664 available : int64; (** Remaining free space bytes. *)
667 val lookup_by_name : 'a Connect.t -> string -> 'a t
668 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
669 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
670 (** Look up a storage pool by name, UUID or UUID string. *)
672 val create_xml : [>`W] Connect.t -> xml -> rw t
673 (** Create a storage pool. *)
674 val define_xml : [>`W] Connect.t -> xml -> rw t
675 (** Define but don't activate a storage pool. *)
676 val build : [>`W] t -> pool_build_flags -> unit
677 (** Build a storage pool. *)
678 val undefine : [>`W] t -> unit
679 (** Undefine configuration of a storage pool. *)
680 val create : [>`W] t -> unit
681 (** Start up a defined (inactive) storage pool. *)
682 val destroy : [>`W] t -> unit
683 (** Destroy a storage pool. *)
684 val delete : [>`W] t -> unit
685 (** Delete a storage pool. *)
686 val free : [>`R] t -> unit
687 (** Free a storage pool object in memory.
689 The storage pool object is automatically freed if it is garbage
690 collected. This function just forces it to be freed right
693 val refresh : [`R] t -> unit
694 (** Refresh the list of volumes in the storage pool. *)
696 val get_name : [`R] t -> string
697 (** Name of the pool. *)
698 val get_uuid : [`R] t -> uuid
699 (** Get the UUID (as a packed byte array). *)
700 val get_uuid_string : [`R] t -> string
701 (** Get the UUID (as a printable string). *)
702 val get_info : [`R] t -> pool_info
703 (** Get information about the pool. *)
704 val get_xml_desc : [`R] t -> xml
705 (** Get the XML description. *)
706 val get_autostart : [`R] t -> bool
707 (** Get the autostart flag for the storage pool. *)
708 val set_autostart : [`W] t -> bool -> unit
709 (** Set the autostart flag for the storage pool. *)
711 val num_of_volumes : [`R] t -> int
712 (** Returns the number of storage volumes within the storage pool. *)
713 val list_volumes : [`R] t -> int -> string array
714 (** Return list of storage volumes. *)
716 external const : [>`R] t -> ro t = "%identity"
717 (** [const conn] turns a read/write storage pool into a read-only
718 pool. Note that the opposite operation is impossible.
721 (** Module dealing with storage pools. *)
723 (** {3 Storage volumes} *)
728 (** Storage volume handle. *)
730 type vol_type = File | Block
731 (** Type of a storage volume. *)
733 type vol_delete_flags = Normal | Zeroed
734 (** Flags for deleting a storage volume. *)
737 typ : vol_type; (** Type of storage volume. *)
738 capacity : int64; (** Logical size in bytes. *)
739 allocation : int64; (** Currently allocated in bytes. *)
742 val lookup_by_name : 'a Pool.t -> string -> 'a t
743 val lookup_by_key : 'a Connect.t -> string -> 'a t
744 val lookup_by_path : 'a Connect.t -> string -> 'a t
745 (** Look up a storage volume by name, key or path volume. *)
747 val pool_of_volume : 'a t -> 'a Pool.t
748 (** Get the storage pool containing this volume. *)
750 val get_name : [`R] t -> string
751 (** Name of the volume. *)
752 val get_key : [`R] t -> string
753 (** Key of the volume. *)
754 val get_path : [`R] t -> string
755 (** Path of the volume. *)
756 val get_info : [`R] t -> vol_info
757 (** Get information about the storage volume. *)
758 val get_xml_desc : [`R] t -> xml
759 (** Get the XML description. *)
761 val create_xml : [`W] Pool.t -> xml -> unit
762 (** Create a storage volume. *)
763 val delete : [`W] t -> unit
764 (** Delete a storage volume. *)
765 val free : [>`R] t -> unit
766 (** Free a storage volume object in memory.
768 The storage volume object is automatically freed if it is garbage
769 collected. This function just forces it to be freed right
773 external const : [>`R] t -> ro t = "%identity"
774 (** [const conn] turns a read/write storage volume into a read-only
775 volume. Note that the opposite operation is impossible.
778 (** Module dealing with storage volumes. *)
780 (** {3 Jobs and asynchronous processing} *)
784 type ('jobclass, 'rw) t = ('jobclass, 'rw) job_t
785 (** A background asynchronous job.
787 Jobs represent a pending operation such as domain creation.
788 The possible types for a job are:
791 (`Domain, `W) Job.t Job creating a new domain
792 (`Domain_nocreate, `W) Job.t Job acting on an existing domain
793 (`Network, `W) Job.t Job creating a new network
794 (`Network_nocreate, `W) Job.t Job acting on an existing network
798 type job_type = Bounded | Unbounded
799 (** A Bounded job is one where we can estimate time to completion. *)
801 type job_state = Running | Complete | Failed | Cancelled
802 (** State of the job. *)
805 typ : job_type; (** Job type (Bounded, Unbounded) *)
806 state : job_state; (** Job state (Running, etc.) *)
807 running_time : int; (** Actual running time (seconds) *)
808 (** The following fields are only available in Bounded jobs: *)
809 remaining_time : int; (** Estimated time left (seconds) *)
810 percent_complete : int (** Estimated percent complete *)
813 val get_info : ('a,'b) t -> job_info
814 (** Get information and status about the job. *)
816 val get_domain : ([`Domain], 'a) t -> 'a Domain.t
817 (** Get the completed domain from a job.
819 You should only call it on a job in state Complete. *)
821 val get_network : ([`Network], 'a) t -> 'a Network.t
822 (** Get the completed network from a job.
824 You should only call it on a job in state Complete. *)
826 val cancel : ('a,'b) t -> unit
829 val free : ('a, [>`R]) t -> unit
830 (** Free a job object in memory.
832 The job object is automatically freed if it is garbage
833 collected. This function just forces it to be freed right
837 external const : ('a, [>`R]) t -> ('a, ro) t = "%identity"
838 (** [const conn] turns a read/write job into a read-only
839 job. Note that the opposite operation is impossible.
842 (** Module dealing with asynchronous jobs. *)
844 (** {3 Error handling and exceptions} *)
850 | VIR_ERR_INTERNAL_ERROR
853 | VIR_ERR_UNKNOWN_HOST
855 | VIR_ERR_INVALID_CONN
856 | VIR_ERR_INVALID_DOMAIN
857 | VIR_ERR_INVALID_ARG
858 | VIR_ERR_OPERATION_FAILED
860 | VIR_ERR_POST_FAILED
862 | VIR_ERR_SEXPR_SERIAL
873 | VIR_ERR_NO_XENSTORE
874 | VIR_ERR_DRIVER_FULL
875 | VIR_ERR_CALL_FAILED
878 | VIR_ERR_OPERATION_DENIED
879 | VIR_ERR_OPEN_FAILED
880 | VIR_ERR_READ_FAILED
881 | VIR_ERR_PARSE_FAILED
882 | VIR_ERR_CONF_SYNTAX
883 | VIR_ERR_WRITE_FAILED
885 | VIR_ERR_INVALID_NETWORK
886 | VIR_ERR_NETWORK_EXIST
887 | VIR_ERR_SYSTEM_ERROR
889 | VIR_ERR_GNUTLS_ERROR
893 | VIR_ERR_INVALID_MAC
894 | VIR_ERR_AUTH_FAILED
895 | VIR_ERR_INVALID_STORAGE_POOL
896 | VIR_ERR_INVALID_STORAGE_VOL
898 | VIR_ERR_NO_STORAGE_POOL
899 | VIR_ERR_NO_STORAGE_VOL
900 (* ^^ NB: If you add a variant you MUST edit
901 libvirt_c_epilogue.c:MAX_VIR_* *)
902 | VIR_ERR_UNKNOWN of int
903 (** See [<libvirt/virterror.h>] for meaning of these codes. *)
905 val string_of_code : code -> string
924 | VIR_FROM_STATS_LINUX
926 (* ^^ NB: If you add a variant you MUST edit
927 libvirt_c_epilogue.c: MAX_VIR_* *)
928 | VIR_FROM_UNKNOWN of int
929 (** Subsystem / driver which produced the error. *)
931 val string_of_domain : domain -> string
937 (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *)
938 | VIR_ERR_UNKNOWN_LEVEL of int
939 (** No error, a warning or an error. *)
941 val string_of_level : level -> string
944 code : code; (** Error code. *)
945 domain : domain; (** Origin of the error. *)
946 message : string option; (** Human-readable message. *)
947 level : level; (** Error or warning. *)
948 str1 : string option; (** Informational string. *)
949 str2 : string option; (** Informational string. *)
950 str3 : string option; (** Informational string. *)
951 int1 : int32; (** Informational integer. *)
952 int2 : int32; (** Informational integer. *)
954 (** An error object. *)
956 val to_string : t -> string
957 (** Turn the exception into a printable string. *)
959 val get_last_error : unit -> t option
960 val get_last_conn_error : [>`R] Connect.t -> t option
961 (** Get the last error at a global or connection level.
963 Normally you do not need to use these functions because
964 the library automatically turns errors into exceptions.
967 val reset_last_error : unit -> unit
968 val reset_last_conn_error : [>`R] Connect.t -> unit
969 (** Reset the error at a global or connection level.
971 Normally you do not need to use these functions.
974 val no_error : unit -> t
975 (** Creates an empty error message.
977 Normally you do not need to use this function.
980 (** Module dealing with errors. *)
982 exception Virterror of Virterror.t
983 (** This exception can be raised by any library function that detects
984 an error. To get a printable error message, call
985 {!Virterror.to_string} on the content of this exception.
988 exception Not_supported of string
991 [Not_supported "virFoo"]
992 (where [virFoo] is the libvirt function name) if a function is
993 not supported at either compile or run time. This applies to
994 any libvirt function added after version 0.2.1.
996 See also {{:http://libvirt.org/hvsupport.html}http://libvirt.org/hvsupport.html}