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 domains = D.get_domains conn [D.ListActive] in
85 printf "%8d %s\n%!" (D.get_id dom) (D.get_name dom)
89 {3 Example: List inactive domains}
92 let domains = D.get_domains conn [D.ListInactive] in
95 printf "inactive %s\n%!" (D.get_name dom)
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 raise odd exceptions at any time.
141 This is just the nature of virtualisation.
143 {3 Backwards and forwards compatibility}
145 OCaml-libvirt requires libvirt version 1.0.2 or later. Future
146 releases of OCaml-libvirt will use newer features of libvirt
147 and therefore will require later versions of libvirt. It is always
148 possible to dynamically link your application against a newer
149 libvirt than OCaml-libvirt was originally compiled against.
151 {3 Get list of domains and domain infos}
153 This is a very common operation, and libvirt supports various
154 different methods to do it. We have hidden the complexity in a
155 flexible {!Libvirt.Domain.get_domains} and
156 {!Libvirt.Domain.get_domains_and_infos} calls which is easy to use and
157 automatically chooses the most efficient method depending on the
158 version of libvirt in use.
162 You can issue multiple concurrent libvirt requests in
163 different threads. However you must follow this rule:
164 Each thread must have its own separate libvirt connection, {i or}
165 you must implement your own mutex scheme to ensure that no
166 two threads can ever make concurrent calls using the same
169 (Note that multithreaded code is not well tested. If you find
170 bugs please report them.)
174 Libvirt requires all callers to call virInitialize before
175 using the library. This is done automatically for you by
176 these bindings when the program starts up, and we believe
177 that the way this is done is safe.
183 (** This is a "raw" UUID, ie. a packed string of bytes. *)
186 (** Type of XML (an uninterpreted string of bytes). Use PXP, expat,
187 xml-light, etc. if you want to do anything useful with the XML.
190 type filename = string
193 val get_version : ?driver:string -> unit -> int * int
194 (** [get_version ()] returns the library version in the first part
195 of the tuple, and [0] in the second part.
197 [get_version ~driver ()] returns the library version in the first
198 part of the tuple, and the version of the driver called [driver]
201 The version numbers are encoded as
202 1,000,000 * major + 1,000 * minor + release.
205 val uuid_length : int
206 (** Length of packed UUIDs. *)
208 val uuid_string_length : int
209 (** Length of UUID strings. *)
214 {{:http://caml.inria.fr/pub/ml-archives/caml-list/2004/07/80683af867cce6bf8fff273973f70c95.en.html}phantom types}
215 are used to ensure the type-safety of read-only
216 versus read-write connections.
218 All connection/domain/etc. objects are marked with
219 a phantom read-write or read-only type, and trying to
220 pass a read-only object into a function which could
221 mutate the object will cause a compile time error.
223 Each module provides a function like {!Libvirt.Connect.const}
224 to demote a read-write object into a read-only object. The
225 opposite operation is, of course, not allowed.
227 If you want to handle both read-write and read-only
228 connections at runtime, use a variant similar to this:
232 | Read_only of Libvirt.ro Libvirt.Connect.t
233 | Read_write of Libvirt.rw Libvirt.Connect.t
237 (** {3 Forward definitions}
239 These definitions are placed here to avoid the need to
240 use recursive module dependencies.
243 (** {3 Connections} *)
248 (** Connection. Read-only connections have type [ro Connect.t] and
249 read-write connections have type [rw Connect.t].
253 model : string; (** CPU model *)
254 memory : int64; (** memory size in kilobytes *)
255 cpus : int; (** number of active CPUs *)
256 mhz : int; (** expected CPU frequency *)
257 nodes : int; (** number of NUMA nodes (1 = UMA) *)
258 sockets : int; (** number of CPU sockets per node *)
259 cores : int; (** number of cores per socket *)
260 threads : int; (** number of threads per core *)
263 val connect : ?name:string -> unit -> rw t
264 val connect_readonly : ?name:string -> unit -> ro t
265 (** [connect ~name ()] connects to the hypervisor with URI [name].
267 [connect ()] connects to the default hypervisor.
269 [connect_readonly] is the same but connects in read-only mode.
272 val close : [>`R] t -> unit
273 (** [close conn] closes and frees the connection object in memory.
275 The connection is automatically closed if it is garbage
276 collected. This function just forces it to be closed
277 and freed right away.
280 val get_type : [>`R] t -> string
281 (** Returns the name of the driver (hypervisor). *)
283 val get_version : [>`R] t -> int
284 (** Returns the driver version
285 [major * 1_000_000 + minor * 1000 + release]
287 val get_hostname : [>`R] t -> string
288 (** Returns the hostname of the physical server. *)
289 val get_uri : [>`R] t -> string
290 (** Returns the canonical connection URI. *)
291 val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
292 (** Returns the maximum number of virtual CPUs
293 supported by a guest VM of a particular type. *)
294 val list_domains : [>`R] t -> int -> int array
295 (** [list_domains conn max] returns the running domain IDs,
296 up to a maximum of [max] entries.
298 Call {!num_of_domains} first to get a value for [max].
301 {!Libvirt.Domain.get_domains},
302 {!Libvirt.Domain.get_domains_and_infos}.
304 val num_of_domains : [>`R] t -> int
305 (** Returns the number of running domains. *)
306 val get_capabilities : [>`R] t -> xml
307 (** Returns the hypervisor capabilities (as XML). *)
308 val num_of_defined_domains : [>`R] t -> int
309 (** Returns the number of inactive (shutdown) domains. *)
310 val list_defined_domains : [>`R] t -> int -> string array
311 (** [list_defined_domains conn max]
312 returns the names of the inactive domains, up to
313 a maximum of [max] entries.
315 Call {!num_of_defined_domains} first to get a value for [max].
318 {!Libvirt.Domain.get_domains},
319 {!Libvirt.Domain.get_domains_and_infos}.
321 val num_of_networks : [>`R] t -> int
322 (** Returns the number of networks. *)
323 val list_networks : [>`R] t -> int -> string array
324 (** [list_networks conn max]
325 returns the names of the networks, up to a maximum
327 Call {!num_of_networks} first to get a value for [max].
329 val num_of_defined_networks : [>`R] t -> int
330 (** Returns the number of inactive networks. *)
331 val list_defined_networks : [>`R] t -> int -> string array
332 (** [list_defined_networks conn max]
333 returns the names of the inactive networks, up to a maximum
335 Call {!num_of_defined_networks} first to get a value for [max].
338 val num_of_pools : [>`R] t -> int
339 (** Returns the number of storage pools. *)
340 val list_pools : [>`R] t -> int -> string array
341 (** Return list of storage pools. *)
342 val num_of_defined_pools : [>`R] t -> int
343 (** Returns the number of storage pools. *)
344 val list_defined_pools : [>`R] t -> int -> string array
345 (** Return list of storage pools. *)
347 (* The name of this function is inconsistent, but the inconsistency
348 * is really in libvirt itself.
350 val get_node_info : [>`R] t -> node_info
351 (** Return information about the physical server. *)
353 val node_get_free_memory : [> `R] t -> int64
355 [node_get_free_memory conn]
356 returns the amount of free memory (not allocated to any guest)
360 val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array
362 [node_get_cells_free_memory conn start max]
363 returns the amount of free memory on each NUMA cell in kilobytes.
364 [start] is the first cell for which we return free memory.
365 [max] is the maximum number of cells for which we return free memory.
366 Returns an array of up to [max] entries in length.
369 val maxcpus_of_node_info : node_info -> int
370 (** Calculate the total number of CPUs supported (but not necessarily
374 val cpumaplen : int -> int
375 (** Calculate the length (in bytes) required to store the complete
376 CPU map between a single virtual and all physical CPUs of a domain.
379 val use_cpu : string -> int -> unit
380 (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
381 val unuse_cpu : string -> int -> unit
382 (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
383 val cpu_usable : string -> int -> int -> int -> bool
384 (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
385 [cpu] is usable by [vcpu]. *)
387 external const : [>`R] t -> ro t = "%identity"
388 (** [const conn] turns a read/write connection into a read-only
389 connection. Note that the opposite operation is impossible.
392 (** Module dealing with connections. [Connect.t] is the
393 connection object. *)
400 (** Domain handle. Read-only handles have type [ro Domain.t] and
401 read-write handles have type [rw Domain.t].
405 | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
406 | InfoShutdown | InfoShutoff | InfoCrashed
409 state : state; (** running state *)
410 max_mem : int64; (** maximum memory in kilobytes *)
411 memory : int64; (** memory used in kilobytes *)
412 nr_virt_cpu : int; (** number of virtual CPUs *)
413 cpu_time : int64; (** CPU time used in nanoseconds *)
416 type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
419 number : int; (** virtual CPU number *)
420 vcpu_state : vcpu_state; (** state *)
421 vcpu_time : int64; (** CPU time used in nanoseconds *)
422 cpu : int; (** real CPU number, -1 if offline *)
425 type sched_param = string * sched_param_value
426 and sched_param_value =
427 | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
428 | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
429 | SchedFieldFloat of float | SchedFieldBool of bool
431 type typed_param = string * typed_param_value
432 and typed_param_value =
433 | TypedFieldInt32 of int32 | TypedFieldUInt32 of int32
434 | TypedFieldInt64 of int64 | TypedFieldUInt64 of int64
435 | TypedFieldFloat of float | TypedFieldBool of bool
436 | TypedFieldString of string
438 type migrate_flag = Live
440 type memory_flag = Virtual
455 type interface_stats = {
466 val max_peek : [>`R] t -> int
467 (** Maximum size supported by the {!block_peek} and {!memory_peek}
468 functions. If you want to peek more than this then you must
469 break your request into chunks. *)
471 val create_linux : [>`W] Connect.t -> xml -> rw t
472 (** Create a new guest domain (not necessarily a Linux one)
475 val lookup_by_id : 'a Connect.t -> int -> 'a t
476 (** Lookup a domain by ID. *)
477 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
478 (** Lookup a domain by UUID. This uses the packed byte array UUID. *)
479 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
480 (** Lookup a domain by (string) UUID. *)
481 val lookup_by_name : 'a Connect.t -> string -> 'a t
482 (** Lookup a domain by name. *)
483 val destroy : [>`W] t -> unit
484 (** Abruptly destroy a domain. *)
485 val free : [>`R] t -> unit
486 (** [free domain] frees the domain object in memory.
488 The domain object is automatically freed if it is garbage
489 collected. This function just forces it to be freed right
493 val suspend : [>`W] t -> unit
494 (** Suspend a domain. *)
495 val resume : [>`W] t -> unit
496 (** Resume a domain. *)
497 val save : [>`W] t -> filename -> unit
498 (** Suspend a domain, then save it to the file. *)
499 val restore : [>`W] Connect.t -> filename -> unit
500 (** Restore a domain from a file. *)
501 val core_dump : [>`W] t -> filename -> unit
502 (** Force a domain to core dump to the named file. *)
503 val shutdown : [>`W] t -> unit
504 (** Shutdown a domain. *)
505 val reboot : [>`W] t -> unit
506 (** Reboot a domain. *)
507 val get_name : [>`R] t -> string
508 (** Get the domain name. *)
509 val get_uuid : [>`R] t -> uuid
510 (** Get the domain UUID (as a packed byte array). *)
511 val get_uuid_string : [>`R] t -> string
512 (** Get the domain UUID (as a printable string). *)
513 val get_id : [>`R] t -> int
514 (** [get_id dom] returns the ID of the domain. In most cases
515 this returns [-1] if the domain is not running. *)
516 val get_os_type : [>`R] t -> string
517 (** Get the operating system type. *)
518 val get_max_memory : [>`R] t -> int64
519 (** Get the maximum memory allocation. *)
520 val set_max_memory : [>`W] t -> int64 -> unit
521 (** Set the maximum memory allocation. *)
522 val set_memory : [>`W] t -> int64 -> unit
523 (** Set the normal memory allocation. *)
524 val get_info : [>`R] t -> info
525 (** Get information about a domain. *)
526 val get_xml_desc : [>`R] t -> xml
527 (** Get the XML description of a domain. *)
528 val get_scheduler_type : [>`R] t -> string * int
529 (** Get the scheduler type. *)
530 val get_scheduler_parameters : [>`R] t -> int -> sched_param array
531 (** Get the array of scheduler parameters. *)
532 val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
533 (** Set the array of scheduler parameters. *)
534 val define_xml : [>`W] Connect.t -> xml -> rw t
535 (** Define a new domain (but don't start it up) from the XML. *)
536 val undefine : [>`W] t -> unit
537 (** Undefine a domain - removes its configuration. *)
538 val create : [>`W] t -> unit
539 (** Launch a defined (inactive) domain. *)
540 val get_autostart : [>`R] t -> bool
541 (** Get the autostart flag for a domain. *)
542 val set_autostart : [>`W] t -> bool -> unit
543 (** Set the autostart flag for a domain. *)
544 val set_vcpus : [>`W] t -> int -> unit
545 (** Change the number of vCPUs available to a domain. *)
546 val pin_vcpu : [>`W] t -> int -> string -> unit
547 (** [pin_vcpu dom vcpu bitmap] pins a domain vCPU to a bitmap of physical
548 CPUs. See the libvirt documentation for details of the
549 layout of the bitmap. *)
550 val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
551 (** [get_vcpus dom maxinfo maplen] returns the pinning information
552 for a domain. See the libvirt documentation for details
553 of the array and bitmap returned from this function.
555 val get_cpu_stats : [>`R] t -> typed_param list array
556 (** [get_pcpu_stats dom] returns the physical CPU stats
557 for a domain. See the libvirt documentation for details.
559 val get_max_vcpus : [>`R] t -> int
560 (** Returns the maximum number of vCPUs supported for this domain. *)
561 val attach_device : [>`W] t -> xml -> unit
562 (** Attach a device (described by the device XML) to a domain. *)
563 val detach_device : [>`W] t -> xml -> unit
564 (** Detach a device (described by the device XML) from a domain. *)
566 val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
567 ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
568 (** [migrate dom dconn flags ()] migrates a domain to a
569 destination host described by [dconn].
571 The optional flag [?dname] is used to rename the domain.
573 The optional flag [?uri] is used to route the migration.
575 The optional flag [?bandwidth] is used to limit the bandwidth
576 used for migration (in Mbps). *)
578 val block_stats : [>`R] t -> string -> block_stats
579 (** Returns block device stats. *)
580 val interface_stats : [>`R] t -> string -> interface_stats
581 (** Returns network interface stats. *)
583 val block_peek : [>`W] t -> string -> int64 -> int -> string -> int -> unit
584 (** [block_peek dom path offset size buf boff] reads [size] bytes at
585 [offset] in the domain's [path] block device.
587 If successful then the data is written into [buf] starting
588 at offset [boff], for [size] bytes.
590 See also {!max_peek}. *)
591 val memory_peek : [>`W] t -> memory_flag list -> int64 -> int ->
592 string -> int -> unit
593 (** [memory_peek dom Virtual offset size] reads [size] bytes
594 at [offset] in the domain's virtual memory.
596 If successful then the data is written into [buf] starting
597 at offset [boff], for [size] bytes.
599 See also {!max_peek}. *)
601 external const : [>`R] t -> ro t = "%identity"
602 (** [const dom] turns a read/write domain handle into a read-only
603 domain handle. Note that the opposite operation is impossible.
606 val get_domains : ([>`R] as 'a) Connect.t -> list_flag list -> 'a t list
607 (** Get the active and/or inactive domains using the most
608 efficient method available.
611 {!get_domains_and_infos},
612 {!Connect.list_domains},
613 {!Connect.list_defined_domains}.
616 val get_domains_and_infos : ([>`R] as 'a) Connect.t -> list_flag list ->
618 (** This gets the active and/or inactive domains and the
619 domain info for each one using the most efficient
624 {!Connect.list_domains},
625 {!Connect.list_defined_domains},
630 (** Module dealing with domains. [Domain.t] is the
638 (** Network handle. Read-only handles have type [ro Network.t] and
639 read-write handles have type [rw Network.t].
642 val lookup_by_name : 'a Connect.t -> string -> 'a t
643 (** Lookup a network by name. *)
644 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
645 (** Lookup a network by (packed) UUID. *)
646 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
647 (** Lookup a network by UUID string. *)
648 val create_xml : [>`W] Connect.t -> xml -> rw t
649 (** Create a network. *)
650 val define_xml : [>`W] Connect.t -> xml -> rw t
651 (** Define but don't activate a network. *)
652 val undefine : [>`W] t -> unit
653 (** Undefine configuration of a network. *)
654 val create : [>`W] t -> unit
655 (** Start up a defined (inactive) network. *)
656 val destroy : [>`W] t -> unit
657 (** Destroy a network. *)
658 val free : [>`R] t -> unit
659 (** [free network] frees the network object in memory.
661 The network object is automatically freed if it is garbage
662 collected. This function just forces it to be freed right
666 val get_name : [>`R] t -> string
667 (** Get network name. *)
668 val get_uuid : [>`R] t -> uuid
669 (** Get network packed UUID. *)
670 val get_uuid_string : [>`R] t -> string
671 (** Get network UUID as a printable string. *)
672 val get_xml_desc : [>`R] t -> xml
673 (** Get XML description of a network. *)
674 val get_bridge_name : [>`R] t -> string
675 (** Get bridge device name of a network. *)
676 val get_autostart : [>`R] t -> bool
677 (** Get the autostart flag for a network. *)
678 val set_autostart : [>`W] t -> bool -> unit
679 (** Set the autostart flag for a network. *)
681 external const : [>`R] t -> ro t = "%identity"
682 (** [const network] turns a read/write network handle into a read-only
683 network handle. Note that the opposite operation is impossible.
686 (** Module dealing with networks. [Network.t] is the
689 (** {3 Storage pools} *)
694 (** Storage pool handle. *)
696 type pool_state = Inactive | Building | Running | Degraded
697 (** State of the storage pool. *)
699 type pool_build_flags = New | Repair | Resize
700 (** Flags for creating a storage pool. *)
702 type pool_delete_flags = Normal | Zeroed
703 (** Flags for deleting a storage pool. *)
706 state : pool_state; (** Pool state. *)
707 capacity : int64; (** Logical size in bytes. *)
708 allocation : int64; (** Currently allocated in bytes. *)
709 available : int64; (** Remaining free space bytes. *)
712 val lookup_by_name : 'a Connect.t -> string -> 'a t
713 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
714 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
715 (** Look up a storage pool by name, UUID or UUID string. *)
717 val create_xml : [>`W] Connect.t -> xml -> rw t
718 (** Create a storage pool. *)
719 val define_xml : [>`W] Connect.t -> xml -> rw t
720 (** Define but don't activate a storage pool. *)
721 val build : [>`W] t -> pool_build_flags -> unit
722 (** Build a storage pool. *)
723 val undefine : [>`W] t -> unit
724 (** Undefine configuration of a storage pool. *)
725 val create : [>`W] t -> unit
726 (** Start up a defined (inactive) storage pool. *)
727 val destroy : [>`W] t -> unit
728 (** Destroy a storage pool. *)
729 val delete : [>`W] t -> unit
730 (** Delete a storage pool. *)
731 val free : [>`R] t -> unit
732 (** Free a storage pool object in memory.
734 The storage pool object is automatically freed if it is garbage
735 collected. This function just forces it to be freed right
738 val refresh : [`R] t -> unit
739 (** Refresh the list of volumes in the storage pool. *)
741 val get_name : [`R] t -> string
742 (** Name of the pool. *)
743 val get_uuid : [`R] t -> uuid
744 (** Get the UUID (as a packed byte array). *)
745 val get_uuid_string : [`R] t -> string
746 (** Get the UUID (as a printable string). *)
747 val get_info : [`R] t -> pool_info
748 (** Get information about the pool. *)
749 val get_xml_desc : [`R] t -> xml
750 (** Get the XML description. *)
751 val get_autostart : [`R] t -> bool
752 (** Get the autostart flag for the storage pool. *)
753 val set_autostart : [>`W] t -> bool -> unit
754 (** Set the autostart flag for the storage pool. *)
756 val num_of_volumes : [`R] t -> int
757 (** Returns the number of storage volumes within the storage pool. *)
758 val list_volumes : [`R] t -> int -> string array
759 (** Return list of storage volumes. *)
761 external const : [>`R] t -> ro t = "%identity"
762 (** [const conn] turns a read/write storage pool into a read-only
763 pool. Note that the opposite operation is impossible.
766 (** Module dealing with storage pools. *)
768 (** {3 Storage volumes} *)
773 (** Storage volume handle. *)
775 type vol_type = File | Block
776 (** Type of a storage volume. *)
778 type vol_delete_flags = Normal | Zeroed
779 (** Flags for deleting a storage volume. *)
782 typ : vol_type; (** Type of storage volume. *)
783 capacity : int64; (** Logical size in bytes. *)
784 allocation : int64; (** Currently allocated in bytes. *)
787 val lookup_by_name : 'a Pool.t -> string -> 'a t
788 val lookup_by_key : 'a Connect.t -> string -> 'a t
789 val lookup_by_path : 'a Connect.t -> string -> 'a t
790 (** Look up a storage volume by name, key or path volume. *)
792 val pool_of_volume : 'a t -> 'a Pool.t
793 (** Get the storage pool containing this volume. *)
795 val get_name : [`R] t -> string
796 (** Name of the volume. *)
797 val get_key : [`R] t -> string
798 (** Key of the volume. *)
799 val get_path : [`R] t -> string
800 (** Path of the volume. *)
801 val get_info : [`R] t -> vol_info
802 (** Get information about the storage volume. *)
803 val get_xml_desc : [`R] t -> xml
804 (** Get the XML description. *)
806 val create_xml : [>`W] Pool.t -> xml -> unit
807 (** Create a storage volume. *)
808 val delete : [>`W] t -> vol_delete_flags -> unit
809 (** Delete a storage volume. *)
810 val free : [>`R] t -> unit
811 (** Free a storage volume object in memory.
813 The storage volume object is automatically freed if it is garbage
814 collected. This function just forces it to be freed right
818 external const : [>`R] t -> ro t = "%identity"
819 (** [const conn] turns a read/write storage volume into a read-only
820 volume. Note that the opposite operation is impossible.
823 (** Module dealing with storage volumes. *)
825 (** {3 Error handling and exceptions} *)
831 | VIR_ERR_INTERNAL_ERROR
834 | VIR_ERR_UNKNOWN_HOST
836 | VIR_ERR_INVALID_CONN
837 | VIR_ERR_INVALID_DOMAIN
838 | VIR_ERR_INVALID_ARG
839 | VIR_ERR_OPERATION_FAILED
841 | VIR_ERR_POST_FAILED
843 | VIR_ERR_SEXPR_SERIAL
854 | VIR_ERR_NO_XENSTORE
855 | VIR_ERR_DRIVER_FULL
856 | VIR_ERR_CALL_FAILED
859 | VIR_ERR_OPERATION_DENIED
860 | VIR_ERR_OPEN_FAILED
861 | VIR_ERR_READ_FAILED
862 | VIR_ERR_PARSE_FAILED
863 | VIR_ERR_CONF_SYNTAX
864 | VIR_ERR_WRITE_FAILED
866 | VIR_ERR_INVALID_NETWORK
867 | VIR_ERR_NETWORK_EXIST
868 | VIR_ERR_SYSTEM_ERROR
870 | VIR_ERR_GNUTLS_ERROR
874 | VIR_ERR_INVALID_MAC
875 | VIR_ERR_AUTH_FAILED
876 | VIR_ERR_INVALID_STORAGE_POOL
877 | VIR_ERR_INVALID_STORAGE_VOL
879 | VIR_ERR_NO_STORAGE_POOL
880 | VIR_ERR_NO_STORAGE_VOL
881 (* ^^ NB: If you add a variant you MUST edit
882 libvirt_c_epilogue.c:MAX_VIR_* *)
883 | VIR_ERR_UNKNOWN of int
884 (** See [<libvirt/virterror.h>] for meaning of these codes. *)
886 val string_of_code : code -> string
905 | VIR_FROM_STATS_LINUX
907 (* ^^ NB: If you add a variant you MUST edit
908 libvirt_c_epilogue.c: MAX_VIR_* *)
909 | VIR_FROM_UNKNOWN of int
910 (** Subsystem / driver which produced the error. *)
912 val string_of_domain : domain -> string
918 (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *)
919 | VIR_ERR_UNKNOWN_LEVEL of int
920 (** No error, a warning or an error. *)
922 val string_of_level : level -> string
925 code : code; (** Error code. *)
926 domain : domain; (** Origin of the error. *)
927 message : string option; (** Human-readable message. *)
928 level : level; (** Error or warning. *)
929 str1 : string option; (** Informational string. *)
930 str2 : string option; (** Informational string. *)
931 str3 : string option; (** Informational string. *)
932 int1 : int32; (** Informational integer. *)
933 int2 : int32; (** Informational integer. *)
935 (** An error object. *)
937 val to_string : t -> string
938 (** Turn the exception into a printable string. *)
940 val get_last_error : unit -> t option
941 val get_last_conn_error : [>`R] Connect.t -> t option
942 (** Get the last error at a global or connection level.
944 Normally you do not need to use these functions because
945 the library automatically turns errors into exceptions.
948 val reset_last_error : unit -> unit
949 val reset_last_conn_error : [>`R] Connect.t -> unit
950 (** Reset the error at a global or connection level.
952 Normally you do not need to use these functions.
955 val no_error : unit -> t
956 (** Creates an empty error message.
958 Normally you do not need to use this function.
961 (** Module dealing with errors. *)
963 exception Virterror of Virterror.t
964 (** This exception can be raised by any library function that detects
965 an error. To get a printable error message, call
966 {!Virterror.to_string} on the content of this exception.
969 exception Not_supported of string
972 [Not_supported "virFoo"]
973 (where [virFoo] is the libvirt function name) if a function is
974 not supported at either compile or run time. This applies to
975 any libvirt function added after version 0.2.1.
977 See also {{:http://libvirt.org/hvsupport.html}http://libvirt.org/hvsupport.html}
980 (** {3 Utility functions} *)
982 val map_ignore_errors : ('a -> 'b) -> 'a list -> 'b list
983 (** [map_ignore_errors f xs] calls function [f] for each element of [xs].
985 This is just like [List.map] except that if [f x] throws a
986 {!Virterror.t} exception, the error is ignored and [f x]
987 is not returned in the final list.
989 This function is primarily useful when dealing with domains which
990 might 'disappear' asynchronously from the currently running