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 is backwards and forwards compatible with
146 any libvirt >= 0.2.1. One consequence of this is that
147 your program can dynamically link to a {i newer} version of
148 libvirt than it was compiled with, and it should still
151 When we link to an older version of libvirt.so, there may
152 be missing functions. If ocaml-libvirt was compiled with
153 gcc, then these are turned into OCaml {!Libvirt.Not_supported}
156 We don't support libvirt < 0.2.1, and never will so don't ask us.
158 {3 Get list of domains and domain infos}
160 This is a very common operation, and libvirt supports various
161 different methods to do it. We have hidden the complexity in a
162 flexible {!Libvirt.Domain.get_domains} and
163 {!Libvirt.Domain.get_domains_and_infos} calls which is easy to use and
164 automatically chooses the most efficient method depending on the
165 version of libvirt in use.
169 You can issue multiple concurrent libvirt requests in
170 different threads. However you must follow this rule:
171 Each thread must have its own separate libvirt connection, {i or}
172 you must implement your own mutex scheme to ensure that no
173 two threads can ever make concurrent calls using the same
176 (Note that multithreaded code is not well tested. If you find
177 bugs please report them.)
181 Libvirt requires all callers to call virInitialize before
182 using the library. This is done automatically for you by
183 these bindings when the program starts up, and we believe
184 that the way this is done is safe.
190 (** This is a "raw" UUID, ie. a packed string of bytes. *)
193 (** Type of XML (an uninterpreted string of bytes). Use PXP, expat,
194 xml-light, etc. if you want to do anything useful with the XML.
197 type filename = string
200 val get_version : ?driver:string -> unit -> int * int
201 (** [get_version ()] returns the library version in the first part
202 of the tuple, and [0] in the second part.
204 [get_version ~driver ()] returns the library version in the first
205 part of the tuple, and the version of the driver called [driver]
208 The version numbers are encoded as
209 1,000,000 * major + 1,000 * minor + release.
212 val uuid_length : int
213 (** Length of packed UUIDs. *)
215 val uuid_string_length : int
216 (** Length of UUID strings. *)
221 {{:http://caml.inria.fr/pub/ml-archives/caml-list/2004/07/80683af867cce6bf8fff273973f70c95.en.html}phantom types}
222 are used to ensure the type-safety of read-only
223 versus read-write connections.
225 All connection/domain/etc. objects are marked with
226 a phantom read-write or read-only type, and trying to
227 pass a read-only object into a function which could
228 mutate the object will cause a compile time error.
230 Each module provides a function like {!Libvirt.Connect.const}
231 to demote a read-write object into a read-only object. The
232 opposite operation is, of course, not allowed.
234 If you want to handle both read-write and read-only
235 connections at runtime, use a variant similar to this:
239 | Read_only of Libvirt.ro Libvirt.Connect.t
240 | Read_write of Libvirt.rw Libvirt.Connect.t
244 (** {3 Forward definitions}
246 These definitions are placed here to avoid the need to
247 use recursive module dependencies.
250 (** {3 Connections} *)
255 (** Connection. Read-only connections have type [ro Connect.t] and
256 read-write connections have type [rw Connect.t].
260 model : string; (** CPU model *)
261 memory : int64; (** memory size in kilobytes *)
262 cpus : int; (** number of active CPUs *)
263 mhz : int; (** expected CPU frequency *)
264 nodes : int; (** number of NUMA nodes (1 = UMA) *)
265 sockets : int; (** number of CPU sockets per node *)
266 cores : int; (** number of cores per socket *)
267 threads : int; (** number of threads per core *)
270 val connect : ?name:string -> unit -> rw t
271 val connect_readonly : ?name:string -> unit -> ro t
272 (** [connect ~name ()] connects to the hypervisor with URI [name].
274 [connect ()] connects to the default hypervisor.
276 [connect_readonly] is the same but connects in read-only mode.
279 val close : [>`R] t -> unit
280 (** [close conn] closes and frees the connection object in memory.
282 The connection is automatically closed if it is garbage
283 collected. This function just forces it to be closed
284 and freed right away.
287 val get_type : [>`R] t -> string
288 (** Returns the name of the driver (hypervisor). *)
290 val get_version : [>`R] t -> int
291 (** Returns the driver version
292 [major * 1_000_000 + minor * 1000 + release]
294 val get_hostname : [>`R] t -> string
295 (** Returns the hostname of the physical server. *)
296 val get_uri : [>`R] t -> string
297 (** Returns the canonical connection URI. *)
298 val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
299 (** Returns the maximum number of virtual CPUs
300 supported by a guest VM of a particular type. *)
301 val list_domains : [>`R] t -> int -> int array
302 (** [list_domains conn max] returns the running domain IDs,
303 up to a maximum of [max] entries.
305 Call {!num_of_domains} first to get a value for [max].
308 {!Libvirt.Domain.get_domains},
309 {!Libvirt.Domain.get_domains_and_infos}.
311 val num_of_domains : [>`R] t -> int
312 (** Returns the number of running domains. *)
313 val get_capabilities : [>`R] t -> xml
314 (** Returns the hypervisor capabilities (as XML). *)
315 val num_of_defined_domains : [>`R] t -> int
316 (** Returns the number of inactive (shutdown) domains. *)
317 val list_defined_domains : [>`R] t -> int -> string array
318 (** [list_defined_domains conn max]
319 returns the names of the inactive domains, up to
320 a maximum of [max] entries.
322 Call {!num_of_defined_domains} first to get a value for [max].
325 {!Libvirt.Domain.get_domains},
326 {!Libvirt.Domain.get_domains_and_infos}.
328 val num_of_networks : [>`R] t -> int
329 (** Returns the number of networks. *)
330 val list_networks : [>`R] t -> int -> string array
331 (** [list_networks conn max]
332 returns the names of the networks, up to a maximum
334 Call {!num_of_networks} first to get a value for [max].
336 val num_of_defined_networks : [>`R] t -> int
337 (** Returns the number of inactive networks. *)
338 val list_defined_networks : [>`R] t -> int -> string array
339 (** [list_defined_networks conn max]
340 returns the names of the inactive networks, up to a maximum
342 Call {!num_of_defined_networks} first to get a value for [max].
345 val num_of_pools : [>`R] t -> int
346 (** Returns the number of storage pools. *)
347 val list_pools : [>`R] t -> int -> string array
348 (** Return list of storage pools. *)
349 val num_of_defined_pools : [>`R] t -> int
350 (** Returns the number of storage pools. *)
351 val list_defined_pools : [>`R] t -> int -> string array
352 (** Return list of storage pools. *)
354 (* The name of this function is inconsistent, but the inconsistency
355 * is really in libvirt itself.
357 val get_node_info : [>`R] t -> node_info
358 (** Return information about the physical server. *)
360 val node_get_free_memory : [> `R] t -> int64
362 [node_get_free_memory conn]
363 returns the amount of free memory (not allocated to any guest)
367 val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array
369 [node_get_cells_free_memory conn start max]
370 returns the amount of free memory on each NUMA cell in kilobytes.
371 [start] is the first cell for which we return free memory.
372 [max] is the maximum number of cells for which we return free memory.
373 Returns an array of up to [max] entries in length.
376 val maxcpus_of_node_info : node_info -> int
377 (** Calculate the total number of CPUs supported (but not necessarily
381 val cpumaplen : int -> int
382 (** Calculate the length (in bytes) required to store the complete
383 CPU map between a single virtual and all physical CPUs of a domain.
386 val use_cpu : string -> int -> unit
387 (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
388 val unuse_cpu : string -> int -> unit
389 (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
390 val cpu_usable : string -> int -> int -> int -> bool
391 (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
392 [cpu] is usable by [vcpu]. *)
394 external const : [>`R] t -> ro t = "%identity"
395 (** [const conn] turns a read/write connection into a read-only
396 connection. Note that the opposite operation is impossible.
399 (** Module dealing with connections. [Connect.t] is the
400 connection object. *)
407 (** Domain handle. Read-only handles have type [ro Domain.t] and
408 read-write handles have type [rw Domain.t].
412 | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
413 | InfoShutdown | InfoShutoff | InfoCrashed
416 state : state; (** running state *)
417 max_mem : int64; (** maximum memory in kilobytes *)
418 memory : int64; (** memory used in kilobytes *)
419 nr_virt_cpu : int; (** number of virtual CPUs *)
420 cpu_time : int64; (** CPU time used in nanoseconds *)
423 type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
426 number : int; (** virtual CPU number *)
427 vcpu_state : vcpu_state; (** state *)
428 vcpu_time : int64; (** CPU time used in nanoseconds *)
429 cpu : int; (** real CPU number, -1 if offline *)
432 type sched_param = string * sched_param_value
433 and sched_param_value =
434 | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
435 | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
436 | SchedFieldFloat of float | SchedFieldBool of bool
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 list_all_domains : 'a Connect.t -> ?want_info:bool -> list_flag list -> 'a t array * info array
472 (** [list_all_domains conn flags] returns all domains which
475 This can return both active and inactive domains. The
476 list of flags controls what domains are returned. See
479 The two arrays returned will have the same length, unless
480 [~want_info] is [false] in which case the info array
481 will be zero-length. The default for [~want_info] is [true].
482 In most cases there is no extra penalty for getting the
483 info fields, or the penalty is insignificant.
485 This call was introduced in libvirt 0.4.5. Because you
486 might dynamically link to an older version of libvirt which
487 doesn't have this call, you should use {!get_domains}
488 or {!get_domains_and_infos} which use the most efficient
489 way to get domains for the available version of libvirt.
491 val create_linux : [>`W] Connect.t -> xml -> rw t
492 (** Create a new guest domain (not necessarily a Linux one)
495 val lookup_by_id : 'a Connect.t -> int -> 'a t
496 (** Lookup a domain by ID. *)
497 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
498 (** Lookup a domain by UUID. This uses the packed byte array UUID. *)
499 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
500 (** Lookup a domain by (string) UUID. *)
501 val lookup_by_name : 'a Connect.t -> string -> 'a t
502 (** Lookup a domain by name. *)
503 val destroy : [>`W] t -> unit
504 (** Abruptly destroy a domain. *)
505 val free : [>`R] t -> unit
506 (** [free domain] frees the domain object in memory.
508 The domain object is automatically freed if it is garbage
509 collected. This function just forces it to be freed right
513 val suspend : [>`W] t -> unit
514 (** Suspend a domain. *)
515 val resume : [>`W] t -> unit
516 (** Resume a domain. *)
517 val save : [>`W] t -> filename -> unit
518 (** Suspend a domain, then save it to the file. *)
519 val restore : [>`W] Connect.t -> filename -> unit
520 (** Restore a domain from a file. *)
521 val core_dump : [>`W] t -> filename -> unit
522 (** Force a domain to core dump to the named file. *)
523 val shutdown : [>`W] t -> unit
524 (** Shutdown a domain. *)
525 val reboot : [>`W] t -> unit
526 (** Reboot a domain. *)
527 val get_name : [>`R] t -> string
528 (** Get the domain name. *)
529 val get_uuid : [>`R] t -> uuid
530 (** Get the domain UUID (as a packed byte array). *)
531 val get_uuid_string : [>`R] t -> string
532 (** Get the domain UUID (as a printable string). *)
533 val get_id : [>`R] t -> int
534 (** [get_id dom] returns the ID of the domain. In most cases
535 this returns [-1] if the domain is not running. *)
536 val get_os_type : [>`R] t -> string
537 (** Get the operating system type. *)
538 val get_max_memory : [>`R] t -> int64
539 (** Get the maximum memory allocation. *)
540 val set_max_memory : [>`W] t -> int64 -> unit
541 (** Set the maximum memory allocation. *)
542 val set_memory : [>`W] t -> int64 -> unit
543 (** Set the normal memory allocation. *)
544 val get_info : [>`R] t -> info
545 (** Get information about a domain. *)
546 val get_xml_desc : [>`R] t -> xml
547 (** Get the XML description of a domain. *)
548 val get_scheduler_type : [>`R] t -> string * int
549 (** Get the scheduler type. *)
550 val get_scheduler_parameters : [>`R] t -> int -> sched_param array
551 (** Get the array of scheduler parameters. *)
552 val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
553 (** Set the array of scheduler parameters. *)
554 val define_xml : [>`W] Connect.t -> xml -> rw t
555 (** Define a new domain (but don't start it up) from the XML. *)
556 val undefine : [>`W] t -> unit
557 (** Undefine a domain - removes its configuration. *)
558 val create : [>`W] t -> unit
559 (** Launch a defined (inactive) domain. *)
560 val get_autostart : [>`R] t -> bool
561 (** Get the autostart flag for a domain. *)
562 val set_autostart : [>`W] t -> bool -> unit
563 (** Set the autostart flag for a domain. *)
564 val set_vcpus : [>`W] t -> int -> unit
565 (** Change the number of vCPUs available to a domain. *)
566 val pin_vcpu : [>`W] t -> int -> string -> unit
567 (** [pin_vcpu dom vcpu bitmap] pins a domain vCPU to a bitmap of physical
568 CPUs. See the libvirt documentation for details of the
569 layout of the bitmap. *)
570 val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
571 (** [get_vcpus dom maxinfo maplen] returns the pinning information
572 for a domain. See the libvirt documentation for details
573 of the array and bitmap returned from this function.
575 val get_max_vcpus : [>`R] t -> int
576 (** Returns the maximum number of vCPUs supported for this domain. *)
577 val attach_device : [>`W] t -> xml -> unit
578 (** Attach a device (described by the device XML) to a domain. *)
579 val detach_device : [>`W] t -> xml -> unit
580 (** Detach a device (described by the device XML) from a domain. *)
582 val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
583 ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
584 (** [migrate dom dconn flags ()] migrates a domain to a
585 destination host described by [dconn].
587 The optional flag [?dname] is used to rename the domain.
589 The optional flag [?uri] is used to route the migration.
591 The optional flag [?bandwidth] is used to limit the bandwidth
592 used for migration (in Mbps). *)
594 val block_stats : [>`R] t -> string -> block_stats
595 (** Returns block device stats. *)
596 val interface_stats : [>`R] t -> string -> interface_stats
597 (** Returns network interface stats. *)
599 val block_peek : [>`W] t -> string -> int64 -> int -> string -> int -> unit
600 (** [block_peek dom path offset size buf boff] reads [size] bytes at
601 [offset] in the domain's [path] block device.
603 If successful then the data is written into [buf] starting
604 at offset [boff], for [size] bytes.
606 See also {!max_peek}. *)
607 val memory_peek : [>`W] t -> memory_flag list -> int64 -> int ->
608 string -> int -> unit
609 (** [memory_peek dom Virtual offset size] reads [size] bytes
610 at [offset] in the domain's virtual memory.
612 If successful then the data is written into [buf] starting
613 at offset [boff], for [size] bytes.
615 See also {!max_peek}. *)
617 external const : [>`R] t -> ro t = "%identity"
618 (** [const dom] turns a read/write domain handle into a read-only
619 domain handle. Note that the opposite operation is impossible.
622 val get_domains : ([>`R] as 'a) Connect.t -> list_flag list -> 'a t list
623 (** Get the active and/or inactive domains using the most
624 efficient method available.
627 {!get_domains_and_infos},
629 {!Connect.list_domains},
630 {!Connect.list_defined_domains}.
633 val get_domains_and_infos : ([>`R] as 'a) Connect.t -> list_flag list ->
635 (** This gets the active and/or inactive domains and the
636 domain info for each one using the most efficient
642 {!Connect.list_domains},
643 {!Connect.list_defined_domains},
648 (** Module dealing with domains. [Domain.t] is the
656 (** Network handle. Read-only handles have type [ro Network.t] and
657 read-write handles have type [rw Network.t].
660 val lookup_by_name : 'a Connect.t -> string -> 'a t
661 (** Lookup a network by name. *)
662 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
663 (** Lookup a network by (packed) UUID. *)
664 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
665 (** Lookup a network by UUID string. *)
666 val create_xml : [>`W] Connect.t -> xml -> rw t
667 (** Create a network. *)
668 val define_xml : [>`W] Connect.t -> xml -> rw t
669 (** Define but don't activate a network. *)
670 val undefine : [>`W] t -> unit
671 (** Undefine configuration of a network. *)
672 val create : [>`W] t -> unit
673 (** Start up a defined (inactive) network. *)
674 val destroy : [>`W] t -> unit
675 (** Destroy a network. *)
676 val free : [>`R] t -> unit
677 (** [free network] frees the network object in memory.
679 The network object is automatically freed if it is garbage
680 collected. This function just forces it to be freed right
684 val get_name : [>`R] t -> string
685 (** Get network name. *)
686 val get_uuid : [>`R] t -> uuid
687 (** Get network packed UUID. *)
688 val get_uuid_string : [>`R] t -> string
689 (** Get network UUID as a printable string. *)
690 val get_xml_desc : [>`R] t -> xml
691 (** Get XML description of a network. *)
692 val get_bridge_name : [>`R] t -> string
693 (** Get bridge device name of a network. *)
694 val get_autostart : [>`R] t -> bool
695 (** Get the autostart flag for a network. *)
696 val set_autostart : [>`W] t -> bool -> unit
697 (** Set the autostart flag for a network. *)
699 external const : [>`R] t -> ro t = "%identity"
700 (** [const network] turns a read/write network handle into a read-only
701 network handle. Note that the opposite operation is impossible.
704 (** Module dealing with networks. [Network.t] is the
707 (** {3 Storage pools} *)
712 (** Storage pool handle. *)
714 type pool_state = Inactive | Building | Running | Degraded
715 (** State of the storage pool. *)
717 type pool_build_flags = New | Repair | Resize
718 (** Flags for creating a storage pool. *)
720 type pool_delete_flags = Normal | Zeroed
721 (** Flags for deleting a storage pool. *)
724 state : pool_state; (** Pool state. *)
725 capacity : int64; (** Logical size in bytes. *)
726 allocation : int64; (** Currently allocated in bytes. *)
727 available : int64; (** Remaining free space bytes. *)
730 val lookup_by_name : 'a Connect.t -> string -> 'a t
731 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
732 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
733 (** Look up a storage pool by name, UUID or UUID string. *)
735 val create_xml : [>`W] Connect.t -> xml -> rw t
736 (** Create a storage pool. *)
737 val define_xml : [>`W] Connect.t -> xml -> rw t
738 (** Define but don't activate a storage pool. *)
739 val build : [>`W] t -> pool_build_flags -> unit
740 (** Build a storage pool. *)
741 val undefine : [>`W] t -> unit
742 (** Undefine configuration of a storage pool. *)
743 val create : [>`W] t -> unit
744 (** Start up a defined (inactive) storage pool. *)
745 val destroy : [>`W] t -> unit
746 (** Destroy a storage pool. *)
747 val delete : [>`W] t -> unit
748 (** Delete a storage pool. *)
749 val free : [>`R] t -> unit
750 (** Free a storage pool object in memory.
752 The storage pool object is automatically freed if it is garbage
753 collected. This function just forces it to be freed right
756 val refresh : [`R] t -> unit
757 (** Refresh the list of volumes in the storage pool. *)
759 val get_name : [`R] t -> string
760 (** Name of the pool. *)
761 val get_uuid : [`R] t -> uuid
762 (** Get the UUID (as a packed byte array). *)
763 val get_uuid_string : [`R] t -> string
764 (** Get the UUID (as a printable string). *)
765 val get_info : [`R] t -> pool_info
766 (** Get information about the pool. *)
767 val get_xml_desc : [`R] t -> xml
768 (** Get the XML description. *)
769 val get_autostart : [`R] t -> bool
770 (** Get the autostart flag for the storage pool. *)
771 val set_autostart : [`W] t -> bool -> unit
772 (** Set the autostart flag for the storage pool. *)
774 val num_of_volumes : [`R] t -> int
775 (** Returns the number of storage volumes within the storage pool. *)
776 val list_volumes : [`R] t -> int -> string array
777 (** Return list of storage volumes. *)
779 external const : [>`R] t -> ro t = "%identity"
780 (** [const conn] turns a read/write storage pool into a read-only
781 pool. Note that the opposite operation is impossible.
784 (** Module dealing with storage pools. *)
786 (** {3 Storage volumes} *)
791 (** Storage volume handle. *)
793 type vol_type = File | Block
794 (** Type of a storage volume. *)
796 type vol_delete_flags = Normal | Zeroed
797 (** Flags for deleting a storage volume. *)
800 typ : vol_type; (** Type of storage volume. *)
801 capacity : int64; (** Logical size in bytes. *)
802 allocation : int64; (** Currently allocated in bytes. *)
805 val lookup_by_name : 'a Pool.t -> string -> 'a t
806 val lookup_by_key : 'a Connect.t -> string -> 'a t
807 val lookup_by_path : 'a Connect.t -> string -> 'a t
808 (** Look up a storage volume by name, key or path volume. *)
810 val pool_of_volume : 'a t -> 'a Pool.t
811 (** Get the storage pool containing this volume. *)
813 val get_name : [`R] t -> string
814 (** Name of the volume. *)
815 val get_key : [`R] t -> string
816 (** Key of the volume. *)
817 val get_path : [`R] t -> string
818 (** Path of the volume. *)
819 val get_info : [`R] t -> vol_info
820 (** Get information about the storage volume. *)
821 val get_xml_desc : [`R] t -> xml
822 (** Get the XML description. *)
824 val create_xml : [`W] Pool.t -> xml -> unit
825 (** Create a storage volume. *)
826 val delete : [`W] t -> unit
827 (** Delete a storage volume. *)
828 val free : [>`R] t -> unit
829 (** Free a storage volume object in memory.
831 The storage volume object is automatically freed if it is garbage
832 collected. This function just forces it to be freed right
836 external const : [>`R] t -> ro t = "%identity"
837 (** [const conn] turns a read/write storage volume into a read-only
838 volume. Note that the opposite operation is impossible.
841 (** Module dealing with storage volumes. *)
843 (** {3 Error handling and exceptions} *)
849 | VIR_ERR_INTERNAL_ERROR
852 | VIR_ERR_UNKNOWN_HOST
854 | VIR_ERR_INVALID_CONN
855 | VIR_ERR_INVALID_DOMAIN
856 | VIR_ERR_INVALID_ARG
857 | VIR_ERR_OPERATION_FAILED
859 | VIR_ERR_POST_FAILED
861 | VIR_ERR_SEXPR_SERIAL
872 | VIR_ERR_NO_XENSTORE
873 | VIR_ERR_DRIVER_FULL
874 | VIR_ERR_CALL_FAILED
877 | VIR_ERR_OPERATION_DENIED
878 | VIR_ERR_OPEN_FAILED
879 | VIR_ERR_READ_FAILED
880 | VIR_ERR_PARSE_FAILED
881 | VIR_ERR_CONF_SYNTAX
882 | VIR_ERR_WRITE_FAILED
884 | VIR_ERR_INVALID_NETWORK
885 | VIR_ERR_NETWORK_EXIST
886 | VIR_ERR_SYSTEM_ERROR
888 | VIR_ERR_GNUTLS_ERROR
892 | VIR_ERR_INVALID_MAC
893 | VIR_ERR_AUTH_FAILED
894 | VIR_ERR_INVALID_STORAGE_POOL
895 | VIR_ERR_INVALID_STORAGE_VOL
897 | VIR_ERR_NO_STORAGE_POOL
898 | VIR_ERR_NO_STORAGE_VOL
899 (* ^^ NB: If you add a variant you MUST edit
900 libvirt_c_epilogue.c:MAX_VIR_* *)
901 | VIR_ERR_UNKNOWN of int
902 (** See [<libvirt/virterror.h>] for meaning of these codes. *)
904 val string_of_code : code -> string
923 | VIR_FROM_STATS_LINUX
925 (* ^^ NB: If you add a variant you MUST edit
926 libvirt_c_epilogue.c: MAX_VIR_* *)
927 | VIR_FROM_UNKNOWN of int
928 (** Subsystem / driver which produced the error. *)
930 val string_of_domain : domain -> string
936 (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *)
937 | VIR_ERR_UNKNOWN_LEVEL of int
938 (** No error, a warning or an error. *)
940 val string_of_level : level -> string
943 code : code; (** Error code. *)
944 domain : domain; (** Origin of the error. *)
945 message : string option; (** Human-readable message. *)
946 level : level; (** Error or warning. *)
947 str1 : string option; (** Informational string. *)
948 str2 : string option; (** Informational string. *)
949 str3 : string option; (** Informational string. *)
950 int1 : int32; (** Informational integer. *)
951 int2 : int32; (** Informational integer. *)
953 (** An error object. *)
955 val to_string : t -> string
956 (** Turn the exception into a printable string. *)
958 val get_last_error : unit -> t option
959 val get_last_conn_error : [>`R] Connect.t -> t option
960 (** Get the last error at a global or connection level.
962 Normally you do not need to use these functions because
963 the library automatically turns errors into exceptions.
966 val reset_last_error : unit -> unit
967 val reset_last_conn_error : [>`R] Connect.t -> unit
968 (** Reset the error at a global or connection level.
970 Normally you do not need to use these functions.
973 val no_error : unit -> t
974 (** Creates an empty error message.
976 Normally you do not need to use this function.
979 (** Module dealing with errors. *)
981 exception Virterror of Virterror.t
982 (** This exception can be raised by any library function that detects
983 an error. To get a printable error message, call
984 {!Virterror.to_string} on the content of this exception.
987 exception Not_supported of string
990 [Not_supported "virFoo"]
991 (where [virFoo] is the libvirt function name) if a function is
992 not supported at either compile or run time. This applies to
993 any libvirt function added after version 0.2.1.
995 See also {{:http://libvirt.org/hvsupport.html}http://libvirt.org/hvsupport.html}
998 (** {3 Utility functions} *)
1000 val map_ignore_errors : ('a -> 'b) -> 'a list -> 'b list
1001 (** [map_ignore_errors f xs] calls function [f] for each element of [xs].
1003 This is just like [List.map] except that if [f x] throws a
1004 {!Virterror.t} exception, the error is ignored and [f x]
1005 is not returned in the final list.
1007 This function is primarily useful when dealing with domains which
1008 might 'disappear' asynchronously from the currently running