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,
9 with the OCaml linking exception described in ../COPYING.LIB.
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Lesser General Public License for more details.
16 You should have received a copy of the GNU Lesser General Public
17 License along with this library; if not, write to the Free Software
18 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
22 {2 Introduction and examples}
24 This is a set of bindings for writing OCaml programs to
25 manage virtual machines through {{:http://libvirt.org/}libvirt}.
27 {3 Using libvirt interactively}
29 Using the interactive toplevel:
33 Objective Caml version 3.10.0
36 # #load "mllibvirt.cma";;
37 # let name = "test:///default";;
38 val name : string = "test:///default"
39 # let conn = Libvirt.Connect.connect_readonly ~name () ;;
40 val conn : Libvirt.ro Libvirt.Connect.t = <abstr>
41 # Libvirt.Connect.get_node_info conn;;
42 : Libvirt.Connect.node_info =
43 {Libvirt.Connect.model = "i686"; Libvirt.Connect.memory = 3145728L;
44 Libvirt.Connect.cpus = 16; Libvirt.Connect.mhz = 1400;
45 Libvirt.Connect.nodes = 2; Libvirt.Connect.sockets = 2;
46 Libvirt.Connect.cores = 2; Libvirt.Connect.threads = 2}
49 {3 Compiling libvirt programs}
51 This command compiles a program to native code:
54 ocamlopt -I +libvirt mllibvirt.cmxa list_domains.ml -o list_domains
57 {3 Example: Connect to the hypervisor}
59 The main modules are {!Libvirt.Connect}, {!Libvirt.Domain} and
60 {!Libvirt.Network} corresponding respectively to the
61 {{:http://libvirt.org/html/libvirt-libvirt.html}virConnect*, virDomain* and virNetwork* functions from libvirt}.
62 For brevity I usually rename these modules like this:
65 module C = Libvirt.Connect
66 module D = Libvirt.Domain
67 module N = Libvirt.Network
70 To get a connection handle, assuming a Xen hypervisor:
74 let conn = C.connect_readonly ~name ()
77 {3 Example: List running domains}
82 let n = C.num_of_domains conn in
83 let ids = C.list_domains conn n in
84 let domains = Array.map (D.lookup_by_id conn) ids in
87 printf "%8d %s\n%!" (D.get_id dom) (D.get_name dom)
91 {3 Example: List inactive domains}
94 let n = C.num_of_defined_domains conn in
95 let names = C.list_defined_domains conn n in
98 printf "inactive %s\n%!" name
102 {3 Example: Print node info}
105 let node_info = C.get_node_info conn in
106 printf "model = %s\n" node_info.C.model;
107 printf "memory = %Ld K\n" node_info.C.memory;
108 printf "cpus = %d\n" node_info.C.cpus;
109 printf "mhz = %d\n" node_info.C.mhz;
110 printf "nodes = %d\n" node_info.C.nodes;
111 printf "sockets = %d\n" node_info.C.sockets;
112 printf "cores = %d\n" node_info.C.cores;
113 printf "threads = %d\n%!" node_info.C.threads;
115 let hostname = C.get_hostname conn in
116 printf "hostname = %s\n%!" hostname;
118 let uri = C.get_uri conn in
119 printf "uri = %s\n%!" uri
125 (** {2 Programming issues}
127 {3 General safety issues}
129 Memory allocation / automatic garbage collection of all libvirt
130 objects should be completely safe. If you find any safety issues
131 or if your 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 {3 Backwards and forwards compatibility}
148 OCaml-libvirt is backwards and forwards compatible with
149 any libvirt >= 0.2.1. One consequence of this is that
150 your program can dynamically link to a {i newer} version of
151 libvirt than it was compiled with, and it should still
154 When we link to an older version of libvirt.so, there may
155 be missing functions. If ocaml-libvirt was compiled with
156 gcc, then these are turned into OCaml {!Libvirt.Not_supported}
159 We don't support libvirt < 0.2.1, and never will so don't ask us.
163 You can issue multiple concurrent libvirt requests in
164 different threads. However you must follow this rule:
165 Each thread must have its own separate libvirt connection, {i or}
166 you must implement your own mutex scheme to ensure that no
167 two threads can ever make concurrent calls using the same
170 (Note that multithreaded code is not well tested. If you find
171 bugs please report them.)
175 Libvirt requires all callers to call virInitialize before
176 using the library. This is done automatically for you by
177 these bindings when the program starts up, and we believe
178 that the way this is done is safe.
184 (** This is a "raw" UUID, ie. a packed string of bytes. *)
187 (** Type of XML (an uninterpreted string of bytes). Use PXP, expat,
188 xml-light, etc. if you want to do anything useful with the XML.
191 type filename = string
194 val get_version : ?driver:string -> unit -> int * int
195 (** [get_version ()] returns the library version in the first part
196 of the tuple, and [0] in the second part.
198 [get_version ~driver ()] returns the library version in the first
199 part of the tuple, and the version of the driver called [driver]
202 The version numbers are encoded as
203 1,000,000 * major + 1,000 * minor + release.
206 val uuid_length : int
207 (** Length of packed UUIDs. *)
209 val uuid_string_length : int
210 (** Length of UUID strings. *)
215 {{:http://caml.inria.fr/pub/ml-archives/caml-list/2004/07/80683af867cce6bf8fff273973f70c95.en.html}phantom types}
216 are used to ensure the type-safety of read-only
217 versus read-write connections.
219 All connection/domain/etc. objects are marked with
220 a phantom read-write or read-only type, and trying to
221 pass a read-only object into a function which could
222 mutate the object will cause a compile time error.
224 Each module provides a function like {!Libvirt.Connect.const}
225 to demote a read-write object into a read-only object. The
226 opposite operation is, of course, not allowed.
228 If you want to handle both read-write and read-only
229 connections at runtime, use a variant similar to this:
233 | Read_only of Libvirt.ro Libvirt.Connect.t
234 | Read_write of Libvirt.rw Libvirt.Connect.t
236 See also the source of [mlvirsh].
240 (** Forward definition of {!Job.t} to avoid recursive module dependencies. *)
242 (** {3 Connections} *)
247 (** Connection. Read-only connections have type [ro Connect.t] and
248 read-write connections have type [rw Connect.t].
252 model : string; (** CPU model *)
253 memory : int64; (** memory size in kilobytes *)
254 cpus : int; (** number of active CPUs *)
255 mhz : int; (** expected CPU frequency *)
256 nodes : int; (** number of NUMA nodes (1 = UMA) *)
257 sockets : int; (** number of CPU sockets per node *)
258 cores : int; (** number of cores per socket *)
259 threads : int; (** number of threads per core *)
262 val connect : ?name:string -> unit -> rw t
263 val connect_readonly : ?name:string -> unit -> ro t
264 (** [connect ~name ()] connects to the hypervisor with URI [name].
266 [connect ()] connects to the default hypervisor.
268 [connect_readonly] is the same but connects in read-only mode.
271 val close : [>`R] t -> unit
272 (** [close conn] closes and frees the connection object in memory.
274 The connection is automatically closed if it is garbage
275 collected. This function just forces it to be closed
276 and freed right away.
279 val get_type : [>`R] t -> string
280 (** Returns the name of the driver (hypervisor). *)
282 val get_version : [>`R] t -> int
283 (** Returns the driver version
284 [major * 1_000_000 + minor * 1000 + release]
286 val get_hostname : [>`R] t -> string
287 (** Returns the hostname of the physical server. *)
288 val get_uri : [>`R] t -> string
289 (** Returns the canonical connection URI. *)
290 val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
291 (** Returns the maximum number of virtual CPUs
292 supported by a guest VM of a particular type. *)
293 val list_domains : [>`R] t -> int -> int array
294 (** [list_domains conn max] returns the running domain IDs,
295 up to a maximum of [max] entries.
296 Call {!num_of_domains} first to get a value for [max].
298 val num_of_domains : [>`R] t -> int
299 (** Returns the number of running domains. *)
300 val get_capabilities : [>`R] t -> xml
301 (** Returns the hypervisor capabilities (as XML). *)
302 val num_of_defined_domains : [>`R] t -> int
303 (** Returns the number of inactive (shutdown) domains. *)
304 val list_defined_domains : [>`R] t -> int -> string array
305 (** [list_defined_domains conn max]
306 returns the names of the inactive domains, up to
307 a maximum of [max] entries.
308 Call {!num_of_defined_domains} first to get a value for [max].
310 val num_of_networks : [>`R] t -> int
311 (** Returns the number of networks. *)
312 val list_networks : [>`R] t -> int -> string array
313 (** [list_networks conn max]
314 returns the names of the networks, up to a maximum
316 Call {!num_of_networks} first to get a value for [max].
318 val num_of_defined_networks : [>`R] t -> int
319 (** Returns the number of inactive networks. *)
320 val list_defined_networks : [>`R] t -> int -> string array
321 (** [list_defined_networks conn max]
322 returns the names of the inactive networks, up to a maximum
324 Call {!num_of_defined_networks} first to get a value for [max].
327 val num_of_pools : [>`R] t -> int
328 (** Returns the number of storage pools. *)
329 val list_pools : [>`R] t -> int -> string array
330 (** Return list of storage pools. *)
331 val num_of_defined_pools : [>`R] t -> int
332 (** Returns the number of storage pools. *)
333 val list_defined_pools : [>`R] t -> int -> string array
334 (** Return list of storage pools. *)
336 (* The name of this function is inconsistent, but the inconsistency
337 * is really in libvirt itself.
339 val get_node_info : [>`R] t -> node_info
340 (** Return information about the physical server. *)
342 val node_get_free_memory : [> `R] t -> int64
344 [node_get_free_memory conn]
345 returns the amount of free memory (not allocated to any guest)
349 val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array
351 [node_get_cells_free_memory conn start max]
352 returns the amount of free memory on each NUMA cell in kilobytes.
353 [start] is the first cell for which we return free memory.
354 [max] is the maximum number of cells for which we return free memory.
355 Returns an array of up to [max] entries in length.
358 val maxcpus_of_node_info : node_info -> int
359 (** Calculate the total number of CPUs supported (but not necessarily
363 val cpumaplen : int -> int
364 (** Calculate the length (in bytes) required to store the complete
365 CPU map between a single virtual and all physical CPUs of a domain.
368 val use_cpu : string -> int -> unit
369 (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
370 val unuse_cpu : string -> int -> unit
371 (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
372 val cpu_usable : string -> int -> int -> int -> bool
373 (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
374 [cpu] is usable by [vcpu]. *)
376 external const : [>`R] t -> ro t = "%identity"
377 (** [const conn] turns a read/write connection into a read-only
378 connection. Note that the opposite operation is impossible.
381 (** Module dealing with connections. [Connect.t] is the
382 connection object. *)
389 (** Domain handle. Read-only handles have type [ro Domain.t] and
390 read-write handles have type [rw Domain.t].
394 | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
395 | InfoShutdown | InfoShutoff | InfoCrashed
398 state : state; (** running state *)
399 max_mem : int64; (** maximum memory in kilobytes *)
400 memory : int64; (** memory used in kilobytes *)
401 nr_virt_cpu : int; (** number of virtual CPUs *)
402 cpu_time : int64; (** CPU time used in nanoseconds *)
405 type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
408 number : int; (** virtual CPU number *)
409 vcpu_state : vcpu_state; (** state *)
410 vcpu_time : int64; (** CPU time used in nanoseconds *)
411 cpu : int; (** real CPU number, -1 if offline *)
414 type sched_param = string * sched_param_value
415 and sched_param_value =
416 | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
417 | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
418 | SchedFieldFloat of float | SchedFieldBool of bool
420 type migrate_flag = Live
422 type memory_flag = Virtual
432 type interface_stats = {
443 val max_peek : [>`R] t -> int
444 (** Maximum size supported by the {!block_peek} and {!memory_peek}
445 functions. If you want to peek more than this then you must
446 break your request into chunks. *)
448 val create_linux : [>`W] Connect.t -> xml -> rw t
449 (** Create a new guest domain (not necessarily a Linux one)
452 val create_linux_job : [>`W] Connect.t -> xml -> ([`Domain], rw) job_t
453 (** Asynchronous domain creation. *)
454 val lookup_by_id : 'a Connect.t -> int -> 'a t
455 (** Lookup a domain by ID. *)
456 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
457 (** Lookup a domain by UUID. This uses the packed byte array UUID. *)
458 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
459 (** Lookup a domain by (string) UUID. *)
460 val lookup_by_name : 'a Connect.t -> string -> 'a t
461 (** Lookup a domain by name. *)
462 val destroy : [>`W] t -> unit
463 (** Abruptly destroy a domain. *)
464 val free : [>`R] t -> unit
465 (** [free domain] frees the domain object in memory.
467 The domain object is automatically freed if it is garbage
468 collected. This function just forces it to be freed right
472 val suspend : [>`W] t -> unit
473 (** Suspend a domain. *)
474 val resume : [>`W] t -> unit
475 (** Resume a domain. *)
476 val save : [>`W] t -> filename -> unit
477 (** Suspend a domain, then save it to the file. *)
478 val save_job : [>`W] t -> filename -> ([`Domain_nocreate], rw) job_t
479 (** Asynchronous domain suspend. *)
480 val restore : [>`W] Connect.t -> filename -> unit
481 (** Restore a domain from a file. *)
482 val restore_job : [>`W] Connect.t -> filename -> ([`Domain_nocreate], rw) job_t
483 (** Asynchronous domain restore. *)
484 val core_dump : [>`W] t -> filename -> unit
485 (** Force a domain to core dump to the named file. *)
486 val core_dump_job : [>`W] t -> filename -> ([`Domain_nocreate], rw) job_t
487 (** Asynchronous core dump. *)
488 val shutdown : [>`W] t -> unit
489 (** Shutdown a domain. *)
490 val reboot : [>`W] t -> unit
491 (** Reboot a domain. *)
492 val get_name : [>`R] t -> string
493 (** Get the domain name. *)
494 val get_uuid : [>`R] t -> uuid
495 (** Get the domain UUID (as a packed byte array). *)
496 val get_uuid_string : [>`R] t -> string
497 (** Get the domain UUID (as a printable string). *)
498 val get_id : [>`R] t -> int
499 (** [getid dom] returns the ID of the domain.
501 Do not call this on a defined but not running domain. Those
502 domains don't have IDs, and you'll get an error here.
505 val get_os_type : [>`R] t -> string
506 (** Get the operating system type. *)
507 val get_max_memory : [>`R] t -> int64
508 (** Get the maximum memory allocation. *)
509 val set_max_memory : [>`W] t -> int64 -> unit
510 (** Set the maximum memory allocation. *)
511 val set_memory : [>`W] t -> int64 -> unit
512 (** Set the normal memory allocation. *)
513 val get_info : [>`R] t -> info
514 (** Get information about a domain. *)
515 val get_xml_desc : [>`R] t -> xml
516 (** Get the XML description of a domain. *)
517 val get_scheduler_type : [>`R] t -> string * int
518 (** Get the scheduler type. *)
519 val get_scheduler_parameters : [>`R] t -> int -> sched_param array
520 (** Get the array of scheduler parameters. *)
521 val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
522 (** Set the array of scheduler parameters. *)
523 val define_xml : [>`W] Connect.t -> xml -> rw t
524 (** Define a new domain (but don't start it up) from the XML. *)
525 val undefine : [>`W] t -> unit
526 (** Undefine a domain - removes its configuration. *)
527 val create : [>`W] t -> unit
528 (** Launch a defined (inactive) domain. *)
529 val create_job : [>`W] t -> ([`Domain_nocreate], rw) job_t
530 (** Asynchronous launch domain. *)
531 val get_autostart : [>`R] t -> bool
532 (** Get the autostart flag for a domain. *)
533 val set_autostart : [>`W] t -> bool -> unit
534 (** Set the autostart flag for a domain. *)
535 val set_vcpus : [>`W] t -> int -> unit
536 (** Change the number of vCPUs available to a domain. *)
537 val pin_vcpu : [>`W] t -> int -> string -> unit
538 (** [pin_vcpu dom vcpu bitmap] pins a domain vCPU to a bitmap of physical
539 CPUs. See the libvirt documentation for details of the
540 layout of the bitmap. *)
541 val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
542 (** [get_vcpus dom maxinfo maplen] returns the pinning information
543 for a domain. See the libvirt documentation for details
544 of the array and bitmap returned from this function.
546 val get_max_vcpus : [>`R] t -> int
547 (** Returns the maximum number of vCPUs supported for this domain. *)
548 val attach_device : [>`W] t -> xml -> unit
549 (** Attach a device (described by the device XML) to a domain. *)
550 val detach_device : [>`W] t -> xml -> unit
551 (** Detach a device (described by the device XML) from a domain. *)
553 val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
554 ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
555 (** [migrate dom dconn flags ()] migrates a domain to a
556 destination host described by [dconn].
558 The optional flag [?dname] is used to rename the domain.
560 The optional flag [?uri] is used to route the migration.
562 The optional flag [?bandwidth] is used to limit the bandwidth
563 used for migration (in Mbps). *)
565 val block_stats : [>`R] t -> string -> block_stats
566 (** Returns block device stats. *)
567 val interface_stats : [>`R] t -> string -> interface_stats
568 (** Returns network interface stats. *)
570 val block_peek : [>`R] t -> string -> int64 -> int -> string -> int -> unit
571 (** [block_peek dom path offset size buf boff] reads [size] bytes at
572 [offset] in the domain's [path] block device.
574 If successful then the data is written into [buf] starting
575 at offset [boff], for [size] bytes.
577 See also {!max_peek}. *)
578 val memory_peek : [>`R] t -> memory_flag list -> int64 -> int ->
579 string -> int -> unit
580 (** [memory_peek dom Virtual offset size] reads [size] bytes
581 at [offset] in the domain's virtual memory.
583 If successful then the data is written into [buf] starting
584 at offset [boff], for [size] bytes.
586 See also {!max_peek}. *)
588 external const : [>`R] t -> ro t = "%identity"
589 (** [const dom] turns a read/write domain handle into a read-only
590 domain handle. Note that the opposite operation is impossible.
593 (** Module dealing with domains. [Domain.t] is the
601 (** Network handle. Read-only handles have type [ro Network.t] and
602 read-write handles have type [rw Network.t].
605 val lookup_by_name : 'a Connect.t -> string -> 'a t
606 (** Lookup a network by name. *)
607 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
608 (** Lookup a network by (packed) UUID. *)
609 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
610 (** Lookup a network by UUID string. *)
611 val create_xml : [>`W] Connect.t -> xml -> rw t
612 (** Create a network. *)
613 val create_xml_job : [>`W] Connect.t -> xml -> ([`Network], rw) job_t
614 (** Asynchronous create network. *)
615 val define_xml : [>`W] Connect.t -> xml -> rw t
616 (** Define but don't activate a network. *)
617 val undefine : [>`W] t -> unit
618 (** Undefine configuration of a network. *)
619 val create : [>`W] t -> unit
620 (** Start up a defined (inactive) network. *)
621 val create_job : [>`W] t -> ([`Network_nocreate], rw) job_t
622 (** Asynchronous start network. *)
623 val destroy : [>`W] t -> unit
624 (** Destroy a network. *)
625 val free : [>`R] t -> unit
626 (** [free network] frees the network object in memory.
628 The network object is automatically freed if it is garbage
629 collected. This function just forces it to be freed right
633 val get_name : [>`R] t -> string
634 (** Get network name. *)
635 val get_uuid : [>`R] t -> uuid
636 (** Get network packed UUID. *)
637 val get_uuid_string : [>`R] t -> string
638 (** Get network UUID as a printable string. *)
639 val get_xml_desc : [>`R] t -> xml
640 (** Get XML description of a network. *)
641 val get_bridge_name : [>`R] t -> string
642 (** Get bridge device name of a network. *)
643 val get_autostart : [>`R] t -> bool
644 (** Get the autostart flag for a network. *)
645 val set_autostart : [>`W] t -> bool -> unit
646 (** Set the autostart flag for a network. *)
648 external const : [>`R] t -> ro t = "%identity"
649 (** [const network] turns a read/write network handle into a read-only
650 network handle. Note that the opposite operation is impossible.
653 (** Module dealing with networks. [Network.t] is the
656 (** {3 Storage pools} *)
661 (** Storage pool handle. *)
663 type pool_state = Inactive | Building | Running | Degraded
664 (** State of the storage pool. *)
666 type pool_build_flags = New | Repair | Resize
667 (** Flags for creating a storage pool. *)
669 type pool_delete_flags = Normal | Zeroed
670 (** Flags for deleting a storage pool. *)
673 state : pool_state; (** Pool state. *)
674 capacity : int64; (** Logical size in bytes. *)
675 allocation : int64; (** Currently allocated in bytes. *)
676 available : int64; (** Remaining free space bytes. *)
679 val lookup_by_name : 'a Connect.t -> string -> 'a t
680 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
681 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
682 (** Look up a storage pool by name, UUID or UUID string. *)
684 val create_xml : [>`W] Connect.t -> xml -> rw t
685 (** Create a storage pool. *)
686 val define_xml : [>`W] Connect.t -> xml -> rw t
687 (** Define but don't activate a storage pool. *)
688 val build : [>`W] t -> pool_build_flags -> unit
689 (** Build a storage pool. *)
690 val undefine : [>`W] t -> unit
691 (** Undefine configuration of a storage pool. *)
692 val create : [>`W] t -> unit
693 (** Start up a defined (inactive) storage pool. *)
694 val destroy : [>`W] t -> unit
695 (** Destroy a storage pool. *)
696 val delete : [>`W] t -> unit
697 (** Delete a storage pool. *)
698 val free : [>`R] t -> unit
699 (** Free a storage pool object in memory.
701 The storage pool object is automatically freed if it is garbage
702 collected. This function just forces it to be freed right
705 val refresh : [`R] t -> unit
706 (** Refresh the list of volumes in the storage pool. *)
708 val get_name : [`R] t -> string
709 (** Name of the pool. *)
710 val get_uuid : [`R] t -> uuid
711 (** Get the UUID (as a packed byte array). *)
712 val get_uuid_string : [`R] t -> string
713 (** Get the UUID (as a printable string). *)
714 val get_info : [`R] t -> pool_info
715 (** Get information about the pool. *)
716 val get_xml_desc : [`R] t -> xml
717 (** Get the XML description. *)
718 val get_autostart : [`R] t -> bool
719 (** Get the autostart flag for the storage pool. *)
720 val set_autostart : [`W] t -> bool -> unit
721 (** Set the autostart flag for the storage pool. *)
723 val num_of_volumes : [`R] t -> int
724 (** Returns the number of storage volumes within the storage pool. *)
725 val list_volumes : [`R] t -> int -> string array
726 (** Return list of storage volumes. *)
728 external const : [>`R] t -> ro t = "%identity"
729 (** [const conn] turns a read/write storage pool into a read-only
730 pool. Note that the opposite operation is impossible.
733 (** Module dealing with storage pools. *)
735 (** {3 Storage volumes} *)
740 (** Storage volume handle. *)
742 type vol_type = File | Block
743 (** Type of a storage volume. *)
745 type vol_delete_flags = Normal | Zeroed
746 (** Flags for deleting a storage volume. *)
749 typ : vol_type; (** Type of storage volume. *)
750 capacity : int64; (** Logical size in bytes. *)
751 allocation : int64; (** Currently allocated in bytes. *)
754 val lookup_by_name : 'a Pool.t -> string -> 'a t
755 val lookup_by_key : 'a Connect.t -> string -> 'a t
756 val lookup_by_path : 'a Connect.t -> string -> 'a t
757 (** Look up a storage volume by name, key or path volume. *)
759 val pool_of_volume : 'a t -> 'a Pool.t
760 (** Get the storage pool containing this volume. *)
762 val get_name : [`R] t -> string
763 (** Name of the volume. *)
764 val get_key : [`R] t -> string
765 (** Key of the volume. *)
766 val get_path : [`R] t -> string
767 (** Path of the volume. *)
768 val get_info : [`R] t -> vol_info
769 (** Get information about the storage volume. *)
770 val get_xml_desc : [`R] t -> xml
771 (** Get the XML description. *)
773 val create_xml : [`W] Pool.t -> xml -> unit
774 (** Create a storage volume. *)
775 val delete : [`W] t -> unit
776 (** Delete a storage volume. *)
777 val free : [>`R] t -> unit
778 (** Free a storage volume object in memory.
780 The storage volume object is automatically freed if it is garbage
781 collected. This function just forces it to be freed right
785 external const : [>`R] t -> ro t = "%identity"
786 (** [const conn] turns a read/write storage volume into a read-only
787 volume. Note that the opposite operation is impossible.
790 (** Module dealing with storage volumes. *)
792 (** {3 Jobs and asynchronous processing} *)
796 type ('jobclass, 'rw) t = ('jobclass, 'rw) job_t
797 (** A background asynchronous job.
799 Jobs represent a pending operation such as domain creation.
800 The possible types for a job are:
803 (`Domain, `W) Job.t Job creating a new domain
804 (`Domain_nocreate, `W) Job.t Job acting on an existing domain
805 (`Network, `W) Job.t Job creating a new network
806 (`Network_nocreate, `W) Job.t Job acting on an existing network
810 type job_type = Bounded | Unbounded
811 (** A Bounded job is one where we can estimate time to completion. *)
813 type job_state = Running | Complete | Failed | Cancelled
814 (** State of the job. *)
817 typ : job_type; (** Job type (Bounded, Unbounded) *)
818 state : job_state; (** Job state (Running, etc.) *)
819 running_time : int; (** Actual running time (seconds) *)
820 (** The following fields are only available in Bounded jobs: *)
821 remaining_time : int; (** Estimated time left (seconds) *)
822 percent_complete : int (** Estimated percent complete *)
825 val get_info : ('a,'b) t -> job_info
826 (** Get information and status about the job. *)
828 val get_domain : ([`Domain], 'a) t -> 'a Domain.t
829 (** Get the completed domain from a job.
831 You should only call it on a job in state Complete. *)
833 val get_network : ([`Network], 'a) t -> 'a Network.t
834 (** Get the completed network from a job.
836 You should only call it on a job in state Complete. *)
838 val cancel : ('a,'b) t -> unit
841 val free : ('a, [>`R]) t -> unit
842 (** Free a job object in memory.
844 The job object is automatically freed if it is garbage
845 collected. This function just forces it to be freed right
849 external const : ('a, [>`R]) t -> ('a, ro) t = "%identity"
850 (** [const conn] turns a read/write job into a read-only
851 job. Note that the opposite operation is impossible.
854 (** Module dealing with asynchronous jobs. *)
856 (** {3 Error handling and exceptions} *)
862 | VIR_ERR_INTERNAL_ERROR
865 | VIR_ERR_UNKNOWN_HOST
867 | VIR_ERR_INVALID_CONN
868 | VIR_ERR_INVALID_DOMAIN
869 | VIR_ERR_INVALID_ARG
870 | VIR_ERR_OPERATION_FAILED
872 | VIR_ERR_POST_FAILED
874 | VIR_ERR_SEXPR_SERIAL
885 | VIR_ERR_NO_XENSTORE
886 | VIR_ERR_DRIVER_FULL
887 | VIR_ERR_CALL_FAILED
890 | VIR_ERR_OPERATION_DENIED
891 | VIR_ERR_OPEN_FAILED
892 | VIR_ERR_READ_FAILED
893 | VIR_ERR_PARSE_FAILED
894 | VIR_ERR_CONF_SYNTAX
895 | VIR_ERR_WRITE_FAILED
897 | VIR_ERR_INVALID_NETWORK
898 | VIR_ERR_NETWORK_EXIST
899 | VIR_ERR_SYSTEM_ERROR
901 | VIR_ERR_GNUTLS_ERROR
905 | VIR_ERR_INVALID_MAC
906 | VIR_ERR_AUTH_FAILED
907 | VIR_ERR_INVALID_STORAGE_POOL
908 | VIR_ERR_INVALID_STORAGE_VOL
910 | VIR_ERR_NO_STORAGE_POOL
911 | VIR_ERR_NO_STORAGE_VOL
912 (* ^^ NB: If you add a variant you MUST edit
913 libvirt_c_epilogue.c:MAX_VIR_* *)
914 | VIR_ERR_UNKNOWN of int
915 (** See [<libvirt/virterror.h>] for meaning of these codes. *)
917 val string_of_code : code -> string
936 | VIR_FROM_STATS_LINUX
938 (* ^^ NB: If you add a variant you MUST edit
939 libvirt_c_epilogue.c: MAX_VIR_* *)
940 | VIR_FROM_UNKNOWN of int
941 (** Subsystem / driver which produced the error. *)
943 val string_of_domain : domain -> string
949 (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *)
950 | VIR_ERR_UNKNOWN_LEVEL of int
951 (** No error, a warning or an error. *)
953 val string_of_level : level -> string
956 code : code; (** Error code. *)
957 domain : domain; (** Origin of the error. *)
958 message : string option; (** Human-readable message. *)
959 level : level; (** Error or warning. *)
960 str1 : string option; (** Informational string. *)
961 str2 : string option; (** Informational string. *)
962 str3 : string option; (** Informational string. *)
963 int1 : int32; (** Informational integer. *)
964 int2 : int32; (** Informational integer. *)
966 (** An error object. *)
968 val to_string : t -> string
969 (** Turn the exception into a printable string. *)
971 val get_last_error : unit -> t option
972 val get_last_conn_error : [>`R] Connect.t -> t option
973 (** Get the last error at a global or connection level.
975 Normally you do not need to use these functions because
976 the library automatically turns errors into exceptions.
979 val reset_last_error : unit -> unit
980 val reset_last_conn_error : [>`R] Connect.t -> unit
981 (** Reset the error at a global or connection level.
983 Normally you do not need to use these functions.
986 val no_error : unit -> t
987 (** Creates an empty error message.
989 Normally you do not need to use this function.
992 (** Module dealing with errors. *)
994 exception Virterror of Virterror.t
995 (** This exception can be raised by any library function that detects
996 an error. To get a printable error message, call
997 {!Virterror.to_string} on the content of this exception.
1000 exception Not_supported of string
1003 [Not_supported "virFoo"]
1004 (where [virFoo] is the libvirt function name) if a function is
1005 not supported at either compile or run time. This applies to
1006 any libvirt function added after version 0.2.1.
1008 See also {{:http://libvirt.org/hvsupport.html}http://libvirt.org/hvsupport.html}