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}
83 fst (Libvirt.get_domains conn ~want_info:false [D.ListActive]) in
86 printf "%8d %s\n%!" (D.get_id dom) (D.get_name dom)
90 {3 Example: List inactive domains}
94 fst (Libvirt.get_domains conn ~want_info:false [D.ListInactive]) in
97 printf "inactive %s\n%!" (D.get_name dom)
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 raise 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.
160 {3 Get list of domains}
162 This is a very common operation, and libvirt supports various
163 different methods to do it. We have hidden the complexity in a
164 flexible {!Libvirt.get_domains} call which is easy to use and
165 automatically chooses the most efficient method depending on the
166 version of libvirt in use.
170 You can issue multiple concurrent libvirt requests in
171 different threads. However you must follow this rule:
172 Each thread must have its own separate libvirt connection, {i or}
173 you must implement your own mutex scheme to ensure that no
174 two threads can ever make concurrent calls using the same
177 (Note that multithreaded code is not well tested. If you find
178 bugs please report them.)
182 Libvirt requires all callers to call virInitialize before
183 using the library. This is done automatically for you by
184 these bindings when the program starts up, and we believe
185 that the way this is done is safe.
191 (** This is a "raw" UUID, ie. a packed string of bytes. *)
194 (** Type of XML (an uninterpreted string of bytes). Use PXP, expat,
195 xml-light, etc. if you want to do anything useful with the XML.
198 type filename = string
201 val get_version : ?driver:string -> unit -> int * int
202 (** [get_version ()] returns the library version in the first part
203 of the tuple, and [0] in the second part.
205 [get_version ~driver ()] returns the library version in the first
206 part of the tuple, and the version of the driver called [driver]
209 The version numbers are encoded as
210 1,000,000 * major + 1,000 * minor + release.
213 val uuid_length : int
214 (** Length of packed UUIDs. *)
216 val uuid_string_length : int
217 (** Length of UUID strings. *)
222 {{:http://caml.inria.fr/pub/ml-archives/caml-list/2004/07/80683af867cce6bf8fff273973f70c95.en.html}phantom types}
223 are used to ensure the type-safety of read-only
224 versus read-write connections.
226 All connection/domain/etc. objects are marked with
227 a phantom read-write or read-only type, and trying to
228 pass a read-only object into a function which could
229 mutate the object will cause a compile time error.
231 Each module provides a function like {!Libvirt.Connect.const}
232 to demote a read-write object into a read-only object. The
233 opposite operation is, of course, not allowed.
235 If you want to handle both read-write and read-only
236 connections at runtime, use a variant similar to this:
240 | Read_only of Libvirt.ro Libvirt.Connect.t
241 | Read_write of Libvirt.rw Libvirt.Connect.t
243 See also the source of [mlvirsh].
246 (** {3 Forward definitions}
248 These definitions are placed here to avoid the need to
249 use recursive module dependencies.
253 (** Forward definition of {!Job.t}. *)
255 (** {3 Connections} *)
260 (** Connection. Read-only connections have type [ro Connect.t] and
261 read-write connections have type [rw Connect.t].
265 model : string; (** CPU model *)
266 memory : int64; (** memory size in kilobytes *)
267 cpus : int; (** number of active CPUs *)
268 mhz : int; (** expected CPU frequency *)
269 nodes : int; (** number of NUMA nodes (1 = UMA) *)
270 sockets : int; (** number of CPU sockets per node *)
271 cores : int; (** number of cores per socket *)
272 threads : int; (** number of threads per core *)
275 val connect : ?name:string -> unit -> rw t
276 val connect_readonly : ?name:string -> unit -> ro t
277 (** [connect ~name ()] connects to the hypervisor with URI [name].
279 [connect ()] connects to the default hypervisor.
281 [connect_readonly] is the same but connects in read-only mode.
284 val close : [>`R] t -> unit
285 (** [close conn] closes and frees the connection object in memory.
287 The connection is automatically closed if it is garbage
288 collected. This function just forces it to be closed
289 and freed right away.
292 val get_type : [>`R] t -> string
293 (** Returns the name of the driver (hypervisor). *)
295 val get_version : [>`R] t -> int
296 (** Returns the driver version
297 [major * 1_000_000 + minor * 1000 + release]
299 val get_hostname : [>`R] t -> string
300 (** Returns the hostname of the physical server. *)
301 val get_uri : [>`R] t -> string
302 (** Returns the canonical connection URI. *)
303 val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
304 (** Returns the maximum number of virtual CPUs
305 supported by a guest VM of a particular type. *)
306 val list_domains : [>`R] t -> int -> int array
307 (** [list_domains conn max] returns the running domain IDs,
308 up to a maximum of [max] entries.
310 Call {!num_of_domains} first to get a value for [max].
312 See also: {!Libvirt.get_domains}.
314 val num_of_domains : [>`R] t -> int
315 (** Returns the number of running domains. *)
316 val get_capabilities : [>`R] t -> xml
317 (** Returns the hypervisor capabilities (as XML). *)
318 val num_of_defined_domains : [>`R] t -> int
319 (** Returns the number of inactive (shutdown) domains. *)
320 val list_defined_domains : [>`R] t -> int -> string array
321 (** [list_defined_domains conn max]
322 returns the names of the inactive domains, up to
323 a maximum of [max] entries.
325 Call {!num_of_defined_domains} first to get a value for [max].
327 See also: {!Libvirt.get_domains}.
329 val num_of_networks : [>`R] t -> int
330 (** Returns the number of networks. *)
331 val list_networks : [>`R] t -> int -> string array
332 (** [list_networks conn max]
333 returns the names of the networks, up to a maximum
335 Call {!num_of_networks} first to get a value for [max].
337 val num_of_defined_networks : [>`R] t -> int
338 (** Returns the number of inactive networks. *)
339 val list_defined_networks : [>`R] t -> int -> string array
340 (** [list_defined_networks conn max]
341 returns the names of the inactive networks, up to a maximum
343 Call {!num_of_defined_networks} first to get a value for [max].
346 val num_of_pools : [>`R] t -> int
347 (** Returns the number of storage pools. *)
348 val list_pools : [>`R] t -> int -> string array
349 (** Return list of storage pools. *)
350 val num_of_defined_pools : [>`R] t -> int
351 (** Returns the number of storage pools. *)
352 val list_defined_pools : [>`R] t -> int -> string array
353 (** Return list of storage pools. *)
355 (* The name of this function is inconsistent, but the inconsistency
356 * is really in libvirt itself.
358 val get_node_info : [>`R] t -> node_info
359 (** Return information about the physical server. *)
361 val node_get_free_memory : [> `R] t -> int64
363 [node_get_free_memory conn]
364 returns the amount of free memory (not allocated to any guest)
368 val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array
370 [node_get_cells_free_memory conn start max]
371 returns the amount of free memory on each NUMA cell in kilobytes.
372 [start] is the first cell for which we return free memory.
373 [max] is the maximum number of cells for which we return free memory.
374 Returns an array of up to [max] entries in length.
377 val maxcpus_of_node_info : node_info -> int
378 (** Calculate the total number of CPUs supported (but not necessarily
382 val cpumaplen : int -> int
383 (** Calculate the length (in bytes) required to store the complete
384 CPU map between a single virtual and all physical CPUs of a domain.
387 val use_cpu : string -> int -> unit
388 (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
389 val unuse_cpu : string -> int -> unit
390 (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
391 val cpu_usable : string -> int -> int -> int -> bool
392 (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
393 [cpu] is usable by [vcpu]. *)
395 external const : [>`R] t -> ro t = "%identity"
396 (** [const conn] turns a read/write connection into a read-only
397 connection. Note that the opposite operation is impossible.
400 (** Module dealing with connections. [Connect.t] is the
401 connection object. *)
408 (** Domain handle. Read-only handles have type [ro Domain.t] and
409 read-write handles have type [rw Domain.t].
413 | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
414 | InfoShutdown | InfoShutoff | InfoCrashed
417 state : state; (** running state *)
418 max_mem : int64; (** maximum memory in kilobytes *)
419 memory : int64; (** memory used in kilobytes *)
420 nr_virt_cpu : int; (** number of virtual CPUs *)
421 cpu_time : int64; (** CPU time used in nanoseconds *)
424 type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
427 number : int; (** virtual CPU number *)
428 vcpu_state : vcpu_state; (** state *)
429 vcpu_time : int64; (** CPU time used in nanoseconds *)
430 cpu : int; (** real CPU number, -1 if offline *)
433 type sched_param = string * sched_param_value
434 and sched_param_value =
435 | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
436 | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
437 | SchedFieldFloat of float | SchedFieldBool of bool
439 type migrate_flag = Live
441 type memory_flag = Virtual
444 | ListNoState | ListRunning | ListBlocked
445 | ListPaused | ListShutdown | ListShutoff | ListCrashed
458 type interface_stats = {
469 val max_peek : [>`R] t -> int
470 (** Maximum size supported by the {!block_peek} and {!memory_peek}
471 functions. If you want to peek more than this then you must
472 break your request into chunks. *)
474 val list_all_domains : 'a Connect.t -> ?want_info:bool -> list_flag list -> 'a t array * info array
475 (** [list_all_domains conn flags] returns all domains which
478 This can return both active and inactive domains. The
479 list of flags controls what domains are returned. See
482 The two arrays returned will have the same length, unless
483 [~want_info] is [false] in which case the info array
484 will be zero-length. The default for [~want_info] is [true].
485 In most cases there is no extra penalty for getting the
486 info fields, or the penalty is insignificant.
488 This call was introduced in libvirt 0.4.5. Because you
489 might dynamically link to an older version of libvirt which
490 doesn't have this call, you should use {!Libvirt.get_domains}
491 which uses the most efficient way to get domains for the
492 available version of libvirt.
494 val create_linux : [>`W] Connect.t -> xml -> rw t
495 (** Create a new guest domain (not necessarily a Linux one)
498 val create_linux_job : [>`W] Connect.t -> xml -> ([`Domain], rw) job_t
499 (** Asynchronous domain creation. *)
500 val lookup_by_id : 'a Connect.t -> int -> 'a t
501 (** Lookup a domain by ID. *)
502 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
503 (** Lookup a domain by UUID. This uses the packed byte array UUID. *)
504 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
505 (** Lookup a domain by (string) UUID. *)
506 val lookup_by_name : 'a Connect.t -> string -> 'a t
507 (** Lookup a domain by name. *)
508 val destroy : [>`W] t -> unit
509 (** Abruptly destroy a domain. *)
510 val free : [>`R] t -> unit
511 (** [free domain] frees the domain object in memory.
513 The domain object is automatically freed if it is garbage
514 collected. This function just forces it to be freed right
518 val suspend : [>`W] t -> unit
519 (** Suspend a domain. *)
520 val resume : [>`W] t -> unit
521 (** Resume a domain. *)
522 val save : [>`W] t -> filename -> unit
523 (** Suspend a domain, then save it to the file. *)
524 val save_job : [>`W] t -> filename -> ([`Domain_nocreate], rw) job_t
525 (** Asynchronous domain suspend. *)
526 val restore : [>`W] Connect.t -> filename -> unit
527 (** Restore a domain from a file. *)
528 val restore_job : [>`W] Connect.t -> filename -> ([`Domain_nocreate], rw) job_t
529 (** Asynchronous domain restore. *)
530 val core_dump : [>`W] t -> filename -> unit
531 (** Force a domain to core dump to the named file. *)
532 val core_dump_job : [>`W] t -> filename -> ([`Domain_nocreate], rw) job_t
533 (** Asynchronous core dump. *)
534 val shutdown : [>`W] t -> unit
535 (** Shutdown a domain. *)
536 val reboot : [>`W] t -> unit
537 (** Reboot a domain. *)
538 val get_name : [>`R] t -> string
539 (** Get the domain name. *)
540 val get_uuid : [>`R] t -> uuid
541 (** Get the domain UUID (as a packed byte array). *)
542 val get_uuid_string : [>`R] t -> string
543 (** Get the domain UUID (as a printable string). *)
544 val get_id : [>`R] t -> int
545 (** [getid dom] returns the ID of the domain.
547 Do not call this on a defined but not running domain. Those
548 domains don't have IDs, and you'll get an error here.
551 val get_os_type : [>`R] t -> string
552 (** Get the operating system type. *)
553 val get_max_memory : [>`R] t -> int64
554 (** Get the maximum memory allocation. *)
555 val set_max_memory : [>`W] t -> int64 -> unit
556 (** Set the maximum memory allocation. *)
557 val set_memory : [>`W] t -> int64 -> unit
558 (** Set the normal memory allocation. *)
559 val get_info : [>`R] t -> info
560 (** Get information about a domain. *)
561 val get_xml_desc : [>`R] t -> xml
562 (** Get the XML description of a domain. *)
563 val get_scheduler_type : [>`R] t -> string * int
564 (** Get the scheduler type. *)
565 val get_scheduler_parameters : [>`R] t -> int -> sched_param array
566 (** Get the array of scheduler parameters. *)
567 val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
568 (** Set the array of scheduler parameters. *)
569 val define_xml : [>`W] Connect.t -> xml -> rw t
570 (** Define a new domain (but don't start it up) from the XML. *)
571 val undefine : [>`W] t -> unit
572 (** Undefine a domain - removes its configuration. *)
573 val create : [>`W] t -> unit
574 (** Launch a defined (inactive) domain. *)
575 val create_job : [>`W] t -> ([`Domain_nocreate], rw) job_t
576 (** Asynchronous launch domain. *)
577 val get_autostart : [>`R] t -> bool
578 (** Get the autostart flag for a domain. *)
579 val set_autostart : [>`W] t -> bool -> unit
580 (** Set the autostart flag for a domain. *)
581 val set_vcpus : [>`W] t -> int -> unit
582 (** Change the number of vCPUs available to a domain. *)
583 val pin_vcpu : [>`W] t -> int -> string -> unit
584 (** [pin_vcpu dom vcpu bitmap] pins a domain vCPU to a bitmap of physical
585 CPUs. See the libvirt documentation for details of the
586 layout of the bitmap. *)
587 val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
588 (** [get_vcpus dom maxinfo maplen] returns the pinning information
589 for a domain. See the libvirt documentation for details
590 of the array and bitmap returned from this function.
592 val get_max_vcpus : [>`R] t -> int
593 (** Returns the maximum number of vCPUs supported for this domain. *)
594 val attach_device : [>`W] t -> xml -> unit
595 (** Attach a device (described by the device XML) to a domain. *)
596 val detach_device : [>`W] t -> xml -> unit
597 (** Detach a device (described by the device XML) from a domain. *)
599 val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
600 ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
601 (** [migrate dom dconn flags ()] migrates a domain to a
602 destination host described by [dconn].
604 The optional flag [?dname] is used to rename the domain.
606 The optional flag [?uri] is used to route the migration.
608 The optional flag [?bandwidth] is used to limit the bandwidth
609 used for migration (in Mbps). *)
611 val block_stats : [>`R] t -> string -> block_stats
612 (** Returns block device stats. *)
613 val interface_stats : [>`R] t -> string -> interface_stats
614 (** Returns network interface stats. *)
616 val block_peek : [>`R] t -> string -> int64 -> int -> string -> int -> unit
617 (** [block_peek dom path offset size buf boff] reads [size] bytes at
618 [offset] in the domain's [path] block device.
620 If successful then the data is written into [buf] starting
621 at offset [boff], for [size] bytes.
623 See also {!max_peek}. *)
624 val memory_peek : [>`R] t -> memory_flag list -> int64 -> int ->
625 string -> int -> unit
626 (** [memory_peek dom Virtual offset size] reads [size] bytes
627 at [offset] in the domain's virtual memory.
629 If successful then the data is written into [buf] starting
630 at offset [boff], for [size] bytes.
632 See also {!max_peek}. *)
634 external const : [>`R] t -> ro t = "%identity"
635 (** [const dom] turns a read/write domain handle into a read-only
636 domain handle. Note that the opposite operation is impossible.
639 (** Module dealing with domains. [Domain.t] is the
647 (** Network handle. Read-only handles have type [ro Network.t] and
648 read-write handles have type [rw Network.t].
651 val lookup_by_name : 'a Connect.t -> string -> 'a t
652 (** Lookup a network by name. *)
653 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
654 (** Lookup a network by (packed) UUID. *)
655 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
656 (** Lookup a network by UUID string. *)
657 val create_xml : [>`W] Connect.t -> xml -> rw t
658 (** Create a network. *)
659 val create_xml_job : [>`W] Connect.t -> xml -> ([`Network], rw) job_t
660 (** Asynchronous create network. *)
661 val define_xml : [>`W] Connect.t -> xml -> rw t
662 (** Define but don't activate a network. *)
663 val undefine : [>`W] t -> unit
664 (** Undefine configuration of a network. *)
665 val create : [>`W] t -> unit
666 (** Start up a defined (inactive) network. *)
667 val create_job : [>`W] t -> ([`Network_nocreate], rw) job_t
668 (** Asynchronous start network. *)
669 val destroy : [>`W] t -> unit
670 (** Destroy a network. *)
671 val free : [>`R] t -> unit
672 (** [free network] frees the network object in memory.
674 The network object is automatically freed if it is garbage
675 collected. This function just forces it to be freed right
679 val get_name : [>`R] t -> string
680 (** Get network name. *)
681 val get_uuid : [>`R] t -> uuid
682 (** Get network packed UUID. *)
683 val get_uuid_string : [>`R] t -> string
684 (** Get network UUID as a printable string. *)
685 val get_xml_desc : [>`R] t -> xml
686 (** Get XML description of a network. *)
687 val get_bridge_name : [>`R] t -> string
688 (** Get bridge device name of a network. *)
689 val get_autostart : [>`R] t -> bool
690 (** Get the autostart flag for a network. *)
691 val set_autostart : [>`W] t -> bool -> unit
692 (** Set the autostart flag for a network. *)
694 external const : [>`R] t -> ro t = "%identity"
695 (** [const network] turns a read/write network handle into a read-only
696 network handle. Note that the opposite operation is impossible.
699 (** Module dealing with networks. [Network.t] is the
702 (** {3 Storage pools} *)
707 (** Storage pool handle. *)
709 type pool_state = Inactive | Building | Running | Degraded
710 (** State of the storage pool. *)
712 type pool_build_flags = New | Repair | Resize
713 (** Flags for creating a storage pool. *)
715 type pool_delete_flags = Normal | Zeroed
716 (** Flags for deleting a storage pool. *)
719 state : pool_state; (** Pool state. *)
720 capacity : int64; (** Logical size in bytes. *)
721 allocation : int64; (** Currently allocated in bytes. *)
722 available : int64; (** Remaining free space bytes. *)
725 val lookup_by_name : 'a Connect.t -> string -> 'a t
726 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
727 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
728 (** Look up a storage pool by name, UUID or UUID string. *)
730 val create_xml : [>`W] Connect.t -> xml -> rw t
731 (** Create a storage pool. *)
732 val define_xml : [>`W] Connect.t -> xml -> rw t
733 (** Define but don't activate a storage pool. *)
734 val build : [>`W] t -> pool_build_flags -> unit
735 (** Build a storage pool. *)
736 val undefine : [>`W] t -> unit
737 (** Undefine configuration of a storage pool. *)
738 val create : [>`W] t -> unit
739 (** Start up a defined (inactive) storage pool. *)
740 val destroy : [>`W] t -> unit
741 (** Destroy a storage pool. *)
742 val delete : [>`W] t -> unit
743 (** Delete a storage pool. *)
744 val free : [>`R] t -> unit
745 (** Free a storage pool object in memory.
747 The storage pool object is automatically freed if it is garbage
748 collected. This function just forces it to be freed right
751 val refresh : [`R] t -> unit
752 (** Refresh the list of volumes in the storage pool. *)
754 val get_name : [`R] t -> string
755 (** Name of the pool. *)
756 val get_uuid : [`R] t -> uuid
757 (** Get the UUID (as a packed byte array). *)
758 val get_uuid_string : [`R] t -> string
759 (** Get the UUID (as a printable string). *)
760 val get_info : [`R] t -> pool_info
761 (** Get information about the pool. *)
762 val get_xml_desc : [`R] t -> xml
763 (** Get the XML description. *)
764 val get_autostart : [`R] t -> bool
765 (** Get the autostart flag for the storage pool. *)
766 val set_autostart : [`W] t -> bool -> unit
767 (** Set the autostart flag for the storage pool. *)
769 val num_of_volumes : [`R] t -> int
770 (** Returns the number of storage volumes within the storage pool. *)
771 val list_volumes : [`R] t -> int -> string array
772 (** Return list of storage volumes. *)
774 external const : [>`R] t -> ro t = "%identity"
775 (** [const conn] turns a read/write storage pool into a read-only
776 pool. Note that the opposite operation is impossible.
779 (** Module dealing with storage pools. *)
781 (** {3 Storage volumes} *)
786 (** Storage volume handle. *)
788 type vol_type = File | Block
789 (** Type of a storage volume. *)
791 type vol_delete_flags = Normal | Zeroed
792 (** Flags for deleting a storage volume. *)
795 typ : vol_type; (** Type of storage volume. *)
796 capacity : int64; (** Logical size in bytes. *)
797 allocation : int64; (** Currently allocated in bytes. *)
800 val lookup_by_name : 'a Pool.t -> string -> 'a t
801 val lookup_by_key : 'a Connect.t -> string -> 'a t
802 val lookup_by_path : 'a Connect.t -> string -> 'a t
803 (** Look up a storage volume by name, key or path volume. *)
805 val pool_of_volume : 'a t -> 'a Pool.t
806 (** Get the storage pool containing this volume. *)
808 val get_name : [`R] t -> string
809 (** Name of the volume. *)
810 val get_key : [`R] t -> string
811 (** Key of the volume. *)
812 val get_path : [`R] t -> string
813 (** Path of the volume. *)
814 val get_info : [`R] t -> vol_info
815 (** Get information about the storage volume. *)
816 val get_xml_desc : [`R] t -> xml
817 (** Get the XML description. *)
819 val create_xml : [`W] Pool.t -> xml -> unit
820 (** Create a storage volume. *)
821 val delete : [`W] t -> unit
822 (** Delete a storage volume. *)
823 val free : [>`R] t -> unit
824 (** Free a storage volume object in memory.
826 The storage volume object is automatically freed if it is garbage
827 collected. This function just forces it to be freed right
831 external const : [>`R] t -> ro t = "%identity"
832 (** [const conn] turns a read/write storage volume into a read-only
833 volume. Note that the opposite operation is impossible.
836 (** Module dealing with storage volumes. *)
838 (** {3 Jobs and asynchronous processing} *)
842 type ('jobclass, 'rw) t = ('jobclass, 'rw) job_t
843 (** A background asynchronous job.
845 Jobs represent a pending operation such as domain creation.
846 The possible types for a job are:
849 (`Domain, `W) Job.t Job creating a new domain
850 (`Domain_nocreate, `W) Job.t Job acting on an existing domain
851 (`Network, `W) Job.t Job creating a new network
852 (`Network_nocreate, `W) Job.t Job acting on an existing network
856 type job_type = Bounded | Unbounded
857 (** A Bounded job is one where we can estimate time to completion. *)
859 type job_state = Running | Complete | Failed | Cancelled
860 (** State of the job. *)
863 typ : job_type; (** Job type (Bounded, Unbounded) *)
864 state : job_state; (** Job state (Running, etc.) *)
865 running_time : int; (** Actual running time (seconds) *)
866 (** The following fields are only available in Bounded jobs: *)
867 remaining_time : int; (** Estimated time left (seconds) *)
868 percent_complete : int (** Estimated percent complete *)
871 val get_info : ('a,'b) t -> job_info
872 (** Get information and status about the job. *)
874 val get_domain : ([`Domain], 'a) t -> 'a Domain.t
875 (** Get the completed domain from a job.
877 You should only call it on a job in state Complete. *)
879 val get_network : ([`Network], 'a) t -> 'a Network.t
880 (** Get the completed network from a job.
882 You should only call it on a job in state Complete. *)
884 val cancel : ('a,'b) t -> unit
887 val free : ('a, [>`R]) t -> unit
888 (** Free a job object in memory.
890 The job object is automatically freed if it is garbage
891 collected. This function just forces it to be freed right
895 external const : ('a, [>`R]) t -> ('a, ro) t = "%identity"
896 (** [const conn] turns a read/write job into a read-only
897 job. Note that the opposite operation is impossible.
900 (** Module dealing with asynchronous jobs. *)
902 (** {3 Error handling and exceptions} *)
908 | VIR_ERR_INTERNAL_ERROR
911 | VIR_ERR_UNKNOWN_HOST
913 | VIR_ERR_INVALID_CONN
914 | VIR_ERR_INVALID_DOMAIN
915 | VIR_ERR_INVALID_ARG
916 | VIR_ERR_OPERATION_FAILED
918 | VIR_ERR_POST_FAILED
920 | VIR_ERR_SEXPR_SERIAL
931 | VIR_ERR_NO_XENSTORE
932 | VIR_ERR_DRIVER_FULL
933 | VIR_ERR_CALL_FAILED
936 | VIR_ERR_OPERATION_DENIED
937 | VIR_ERR_OPEN_FAILED
938 | VIR_ERR_READ_FAILED
939 | VIR_ERR_PARSE_FAILED
940 | VIR_ERR_CONF_SYNTAX
941 | VIR_ERR_WRITE_FAILED
943 | VIR_ERR_INVALID_NETWORK
944 | VIR_ERR_NETWORK_EXIST
945 | VIR_ERR_SYSTEM_ERROR
947 | VIR_ERR_GNUTLS_ERROR
951 | VIR_ERR_INVALID_MAC
952 | VIR_ERR_AUTH_FAILED
953 | VIR_ERR_INVALID_STORAGE_POOL
954 | VIR_ERR_INVALID_STORAGE_VOL
956 | VIR_ERR_NO_STORAGE_POOL
957 | VIR_ERR_NO_STORAGE_VOL
958 (* ^^ NB: If you add a variant you MUST edit
959 libvirt_c_epilogue.c:MAX_VIR_* *)
960 | VIR_ERR_UNKNOWN of int
961 (** See [<libvirt/virterror.h>] for meaning of these codes. *)
963 val string_of_code : code -> string
982 | VIR_FROM_STATS_LINUX
984 (* ^^ NB: If you add a variant you MUST edit
985 libvirt_c_epilogue.c: MAX_VIR_* *)
986 | VIR_FROM_UNKNOWN of int
987 (** Subsystem / driver which produced the error. *)
989 val string_of_domain : domain -> string
995 (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *)
996 | VIR_ERR_UNKNOWN_LEVEL of int
997 (** No error, a warning or an error. *)
999 val string_of_level : level -> string
1002 code : code; (** Error code. *)
1003 domain : domain; (** Origin of the error. *)
1004 message : string option; (** Human-readable message. *)
1005 level : level; (** Error or warning. *)
1006 str1 : string option; (** Informational string. *)
1007 str2 : string option; (** Informational string. *)
1008 str3 : string option; (** Informational string. *)
1009 int1 : int32; (** Informational integer. *)
1010 int2 : int32; (** Informational integer. *)
1012 (** An error object. *)
1014 val to_string : t -> string
1015 (** Turn the exception into a printable string. *)
1017 val get_last_error : unit -> t option
1018 val get_last_conn_error : [>`R] Connect.t -> t option
1019 (** Get the last error at a global or connection level.
1021 Normally you do not need to use these functions because
1022 the library automatically turns errors into exceptions.
1025 val reset_last_error : unit -> unit
1026 val reset_last_conn_error : [>`R] Connect.t -> unit
1027 (** Reset the error at a global or connection level.
1029 Normally you do not need to use these functions.
1032 val no_error : unit -> t
1033 (** Creates an empty error message.
1035 Normally you do not need to use this function.
1038 (** Module dealing with errors. *)
1040 exception Virterror of Virterror.t
1041 (** This exception can be raised by any library function that detects
1042 an error. To get a printable error message, call
1043 {!Virterror.to_string} on the content of this exception.
1046 exception Not_supported of string
1049 [Not_supported "virFoo"]
1050 (where [virFoo] is the libvirt function name) if a function is
1051 not supported at either compile or run time. This applies to
1052 any libvirt function added after version 0.2.1.
1054 See also {{:http://libvirt.org/hvsupport.html}http://libvirt.org/hvsupport.html}
1057 (** {3 Utility functions} *)
1059 val map_ignore_errors : ('a -> 'b) -> 'a list -> 'b list
1060 (** [map_ignore_errors f xs] calls function [f] for each element of [xs].
1062 This is just like [List.map] except that if [f x] throws a
1063 {!Virterror.t} exception, the error is ignored and [f x]
1064 is not returned in the final list.
1066 This function is primarily useful when dealing with domains which
1067 might 'disappear' asynchronously from the currently running
1071 val get_domains : ([>`R] as 'a) Connect.t -> ?want_info:bool -> Domain.list_flag list -> 'a Domain.t list * Domain.info list
1072 (** Get the active and/or inactive domains using the most
1073 efficient method available.
1075 The two lists returned will have the same length, unless
1076 [~want_info] is [false] in which case the info list will be
1077 zero-length. The default for [~want_info] is [true]. In most
1078 cases there is no extra penalty for getting the info fields, or
1079 the penalty is insignificant.
1082 {!Domain.list_all_domains},
1083 {!Connect.list_domains},
1084 {!Connect.list_defined_domains}.