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
242 See also the source of [mlvirsh].
245 (** {3 Forward definitions}
247 These definitions are placed here to avoid the need to
248 use recursive module dependencies.
251 (** {3 Connections} *)
256 (** Connection. Read-only connections have type [ro Connect.t] and
257 read-write connections have type [rw Connect.t].
261 model : string; (** CPU model *)
262 memory : int64; (** memory size in kilobytes *)
263 cpus : int; (** number of active CPUs *)
264 mhz : int; (** expected CPU frequency *)
265 nodes : int; (** number of NUMA nodes (1 = UMA) *)
266 sockets : int; (** number of CPU sockets per node *)
267 cores : int; (** number of cores per socket *)
268 threads : int; (** number of threads per core *)
271 val connect : ?name:string -> unit -> rw t
272 val connect_readonly : ?name:string -> unit -> ro t
273 (** [connect ~name ()] connects to the hypervisor with URI [name].
275 [connect ()] connects to the default hypervisor.
277 [connect_readonly] is the same but connects in read-only mode.
280 val close : [>`R] t -> unit
281 (** [close conn] closes and frees the connection object in memory.
283 The connection is automatically closed if it is garbage
284 collected. This function just forces it to be closed
285 and freed right away.
288 val get_type : [>`R] t -> string
289 (** Returns the name of the driver (hypervisor). *)
291 val get_version : [>`R] t -> int
292 (** Returns the driver version
293 [major * 1_000_000 + minor * 1000 + release]
295 val get_hostname : [>`R] t -> string
296 (** Returns the hostname of the physical server. *)
297 val get_uri : [>`R] t -> string
298 (** Returns the canonical connection URI. *)
299 val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
300 (** Returns the maximum number of virtual CPUs
301 supported by a guest VM of a particular type. *)
302 val list_domains : [>`R] t -> int -> int array
303 (** [list_domains conn max] returns the running domain IDs,
304 up to a maximum of [max] entries.
306 Call {!num_of_domains} first to get a value for [max].
309 {!Libvirt.Domain.get_domains},
310 {!Libvirt.Domain.get_domains_and_infos}.
312 val num_of_domains : [>`R] t -> int
313 (** Returns the number of running domains. *)
314 val get_capabilities : [>`R] t -> xml
315 (** Returns the hypervisor capabilities (as XML). *)
316 val num_of_defined_domains : [>`R] t -> int
317 (** Returns the number of inactive (shutdown) domains. *)
318 val list_defined_domains : [>`R] t -> int -> string array
319 (** [list_defined_domains conn max]
320 returns the names of the inactive domains, up to
321 a maximum of [max] entries.
323 Call {!num_of_defined_domains} first to get a value for [max].
326 {!Libvirt.Domain.get_domains},
327 {!Libvirt.Domain.get_domains_and_infos}.
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
456 type interface_stats = {
467 val max_peek : [>`R] t -> int
468 (** Maximum size supported by the {!block_peek} and {!memory_peek}
469 functions. If you want to peek more than this then you must
470 break your request into chunks. *)
472 val list_all_domains : 'a Connect.t -> ?want_info:bool -> list_flag list -> 'a t array * info array
473 (** [list_all_domains conn flags] returns all domains which
476 This can return both active and inactive domains. The
477 list of flags controls what domains are returned. See
480 The two arrays returned will have the same length, unless
481 [~want_info] is [false] in which case the info array
482 will be zero-length. The default for [~want_info] is [true].
483 In most cases there is no extra penalty for getting the
484 info fields, or the penalty is insignificant.
486 This call was introduced in libvirt 0.4.5. Because you
487 might dynamically link to an older version of libvirt which
488 doesn't have this call, you should use {!get_domains}
489 or {!get_domains_and_infos} which use the most efficient
490 way to get domains for the available version of libvirt.
492 val create_linux : [>`W] Connect.t -> xml -> rw t
493 (** Create a new guest domain (not necessarily a Linux one)
496 val lookup_by_id : 'a Connect.t -> int -> 'a t
497 (** Lookup a domain by ID. *)
498 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
499 (** Lookup a domain by UUID. This uses the packed byte array UUID. *)
500 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
501 (** Lookup a domain by (string) UUID. *)
502 val lookup_by_name : 'a Connect.t -> string -> 'a t
503 (** Lookup a domain by name. *)
504 val destroy : [>`W] t -> unit
505 (** Abruptly destroy a domain. *)
506 val free : [>`R] t -> unit
507 (** [free domain] frees the domain object in memory.
509 The domain object is automatically freed if it is garbage
510 collected. This function just forces it to be freed right
514 val suspend : [>`W] t -> unit
515 (** Suspend a domain. *)
516 val resume : [>`W] t -> unit
517 (** Resume a domain. *)
518 val save : [>`W] t -> filename -> unit
519 (** Suspend a domain, then save it to the file. *)
520 val restore : [>`W] Connect.t -> filename -> unit
521 (** Restore a domain from a file. *)
522 val core_dump : [>`W] t -> filename -> unit
523 (** Force a domain to core dump to the named file. *)
524 val shutdown : [>`W] t -> unit
525 (** Shutdown a domain. *)
526 val reboot : [>`W] t -> unit
527 (** Reboot a domain. *)
528 val get_name : [>`R] t -> string
529 (** Get the domain name. *)
530 val get_uuid : [>`R] t -> uuid
531 (** Get the domain UUID (as a packed byte array). *)
532 val get_uuid_string : [>`R] t -> string
533 (** Get the domain UUID (as a printable string). *)
534 val get_id : [>`R] t -> int
535 (** [get_id dom] returns the ID of the domain. In most cases
536 this returns [-1] if the domain is not running. *)
537 val get_os_type : [>`R] t -> string
538 (** Get the operating system type. *)
539 val get_max_memory : [>`R] t -> int64
540 (** Get the maximum memory allocation. *)
541 val set_max_memory : [>`W] t -> int64 -> unit
542 (** Set the maximum memory allocation. *)
543 val set_memory : [>`W] t -> int64 -> unit
544 (** Set the normal memory allocation. *)
545 val get_info : [>`R] t -> info
546 (** Get information about a domain. *)
547 val get_xml_desc : [>`R] t -> xml
548 (** Get the XML description of a domain. *)
549 val get_scheduler_type : [>`R] t -> string * int
550 (** Get the scheduler type. *)
551 val get_scheduler_parameters : [>`R] t -> int -> sched_param array
552 (** Get the array of scheduler parameters. *)
553 val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
554 (** Set the array of scheduler parameters. *)
555 val define_xml : [>`W] Connect.t -> xml -> rw t
556 (** Define a new domain (but don't start it up) from the XML. *)
557 val undefine : [>`W] t -> unit
558 (** Undefine a domain - removes its configuration. *)
559 val create : [>`W] t -> unit
560 (** Launch a defined (inactive) domain. *)
561 val get_autostart : [>`R] t -> bool
562 (** Get the autostart flag for a domain. *)
563 val set_autostart : [>`W] t -> bool -> unit
564 (** Set the autostart flag for a domain. *)
565 val set_vcpus : [>`W] t -> int -> unit
566 (** Change the number of vCPUs available to a domain. *)
567 val pin_vcpu : [>`W] t -> int -> string -> unit
568 (** [pin_vcpu dom vcpu bitmap] pins a domain vCPU to a bitmap of physical
569 CPUs. See the libvirt documentation for details of the
570 layout of the bitmap. *)
571 val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
572 (** [get_vcpus dom maxinfo maplen] returns the pinning information
573 for a domain. See the libvirt documentation for details
574 of the array and bitmap returned from this function.
576 val get_max_vcpus : [>`R] t -> int
577 (** Returns the maximum number of vCPUs supported for this domain. *)
578 val attach_device : [>`W] t -> xml -> unit
579 (** Attach a device (described by the device XML) to a domain. *)
580 val detach_device : [>`W] t -> xml -> unit
581 (** Detach a device (described by the device XML) from a domain. *)
583 val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
584 ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
585 (** [migrate dom dconn flags ()] migrates a domain to a
586 destination host described by [dconn].
588 The optional flag [?dname] is used to rename the domain.
590 The optional flag [?uri] is used to route the migration.
592 The optional flag [?bandwidth] is used to limit the bandwidth
593 used for migration (in Mbps). *)
595 val block_stats : [>`R] t -> string -> block_stats
596 (** Returns block device stats. *)
597 val interface_stats : [>`R] t -> string -> interface_stats
598 (** Returns network interface stats. *)
600 val block_peek : [>`W] t -> string -> int64 -> int -> string -> int -> unit
601 (** [block_peek dom path offset size buf boff] reads [size] bytes at
602 [offset] in the domain's [path] block device.
604 If successful then the data is written into [buf] starting
605 at offset [boff], for [size] bytes.
607 See also {!max_peek}. *)
608 val memory_peek : [>`W] t -> memory_flag list -> int64 -> int ->
609 string -> int -> unit
610 (** [memory_peek dom Virtual offset size] reads [size] bytes
611 at [offset] in the domain's virtual memory.
613 If successful then the data is written into [buf] starting
614 at offset [boff], for [size] bytes.
616 See also {!max_peek}. *)
618 external const : [>`R] t -> ro t = "%identity"
619 (** [const dom] turns a read/write domain handle into a read-only
620 domain handle. Note that the opposite operation is impossible.
623 val get_domains : ([>`R] as 'a) Connect.t -> list_flag list -> 'a t list
624 (** Get the active and/or inactive domains using the most
625 efficient method available.
628 {!get_domains_and_infos},
630 {!Connect.list_domains},
631 {!Connect.list_defined_domains}.
634 val get_domains_and_infos : ([>`R] as 'a) Connect.t -> list_flag list ->
636 (** This gets the active and/or inactive domains and the
637 domain info for each one using the most efficient
643 {!Connect.list_domains},
644 {!Connect.list_defined_domains},
649 (** Module dealing with domains. [Domain.t] is the
657 (** Network handle. Read-only handles have type [ro Network.t] and
658 read-write handles have type [rw Network.t].
661 val lookup_by_name : 'a Connect.t -> string -> 'a t
662 (** Lookup a network by name. *)
663 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
664 (** Lookup a network by (packed) UUID. *)
665 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
666 (** Lookup a network by UUID string. *)
667 val create_xml : [>`W] Connect.t -> xml -> rw t
668 (** Create a network. *)
669 val define_xml : [>`W] Connect.t -> xml -> rw t
670 (** Define but don't activate a network. *)
671 val undefine : [>`W] t -> unit
672 (** Undefine configuration of a network. *)
673 val create : [>`W] t -> unit
674 (** Start up a defined (inactive) network. *)
675 val destroy : [>`W] t -> unit
676 (** Destroy a network. *)
677 val free : [>`R] t -> unit
678 (** [free network] frees the network object in memory.
680 The network object is automatically freed if it is garbage
681 collected. This function just forces it to be freed right
685 val get_name : [>`R] t -> string
686 (** Get network name. *)
687 val get_uuid : [>`R] t -> uuid
688 (** Get network packed UUID. *)
689 val get_uuid_string : [>`R] t -> string
690 (** Get network UUID as a printable string. *)
691 val get_xml_desc : [>`R] t -> xml
692 (** Get XML description of a network. *)
693 val get_bridge_name : [>`R] t -> string
694 (** Get bridge device name of a network. *)
695 val get_autostart : [>`R] t -> bool
696 (** Get the autostart flag for a network. *)
697 val set_autostart : [>`W] t -> bool -> unit
698 (** Set the autostart flag for a network. *)
700 external const : [>`R] t -> ro t = "%identity"
701 (** [const network] turns a read/write network handle into a read-only
702 network handle. Note that the opposite operation is impossible.
705 (** Module dealing with networks. [Network.t] is the
708 (** {3 Storage pools} *)
713 (** Storage pool handle. *)
715 type pool_state = Inactive | Building | Running | Degraded
716 (** State of the storage pool. *)
718 type pool_build_flags = New | Repair | Resize
719 (** Flags for creating a storage pool. *)
721 type pool_delete_flags = Normal | Zeroed
722 (** Flags for deleting a storage pool. *)
725 state : pool_state; (** Pool state. *)
726 capacity : int64; (** Logical size in bytes. *)
727 allocation : int64; (** Currently allocated in bytes. *)
728 available : int64; (** Remaining free space bytes. *)
731 val lookup_by_name : 'a Connect.t -> string -> 'a t
732 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
733 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
734 (** Look up a storage pool by name, UUID or UUID string. *)
736 val create_xml : [>`W] Connect.t -> xml -> rw t
737 (** Create a storage pool. *)
738 val define_xml : [>`W] Connect.t -> xml -> rw t
739 (** Define but don't activate a storage pool. *)
740 val build : [>`W] t -> pool_build_flags -> unit
741 (** Build a storage pool. *)
742 val undefine : [>`W] t -> unit
743 (** Undefine configuration of a storage pool. *)
744 val create : [>`W] t -> unit
745 (** Start up a defined (inactive) storage pool. *)
746 val destroy : [>`W] t -> unit
747 (** Destroy a storage pool. *)
748 val delete : [>`W] t -> unit
749 (** Delete a storage pool. *)
750 val free : [>`R] t -> unit
751 (** Free a storage pool object in memory.
753 The storage pool object is automatically freed if it is garbage
754 collected. This function just forces it to be freed right
757 val refresh : [`R] t -> unit
758 (** Refresh the list of volumes in the storage pool. *)
760 val get_name : [`R] t -> string
761 (** Name of the pool. *)
762 val get_uuid : [`R] t -> uuid
763 (** Get the UUID (as a packed byte array). *)
764 val get_uuid_string : [`R] t -> string
765 (** Get the UUID (as a printable string). *)
766 val get_info : [`R] t -> pool_info
767 (** Get information about the pool. *)
768 val get_xml_desc : [`R] t -> xml
769 (** Get the XML description. *)
770 val get_autostart : [`R] t -> bool
771 (** Get the autostart flag for the storage pool. *)
772 val set_autostart : [`W] t -> bool -> unit
773 (** Set the autostart flag for the storage pool. *)
775 val num_of_volumes : [`R] t -> int
776 (** Returns the number of storage volumes within the storage pool. *)
777 val list_volumes : [`R] t -> int -> string array
778 (** Return list of storage volumes. *)
780 external const : [>`R] t -> ro t = "%identity"
781 (** [const conn] turns a read/write storage pool into a read-only
782 pool. Note that the opposite operation is impossible.
785 (** Module dealing with storage pools. *)
787 (** {3 Storage volumes} *)
792 (** Storage volume handle. *)
794 type vol_type = File | Block
795 (** Type of a storage volume. *)
797 type vol_delete_flags = Normal | Zeroed
798 (** Flags for deleting a storage volume. *)
801 typ : vol_type; (** Type of storage volume. *)
802 capacity : int64; (** Logical size in bytes. *)
803 allocation : int64; (** Currently allocated in bytes. *)
806 val lookup_by_name : 'a Pool.t -> string -> 'a t
807 val lookup_by_key : 'a Connect.t -> string -> 'a t
808 val lookup_by_path : 'a Connect.t -> string -> 'a t
809 (** Look up a storage volume by name, key or path volume. *)
811 val pool_of_volume : 'a t -> 'a Pool.t
812 (** Get the storage pool containing this volume. *)
814 val get_name : [`R] t -> string
815 (** Name of the volume. *)
816 val get_key : [`R] t -> string
817 (** Key of the volume. *)
818 val get_path : [`R] t -> string
819 (** Path of the volume. *)
820 val get_info : [`R] t -> vol_info
821 (** Get information about the storage volume. *)
822 val get_xml_desc : [`R] t -> xml
823 (** Get the XML description. *)
825 val create_xml : [`W] Pool.t -> xml -> unit
826 (** Create a storage volume. *)
827 val delete : [`W] t -> unit
828 (** Delete a storage volume. *)
829 val free : [>`R] t -> unit
830 (** Free a storage volume object in memory.
832 The storage volume object is automatically freed if it is garbage
833 collected. This function just forces it to be freed right
837 external const : [>`R] t -> ro t = "%identity"
838 (** [const conn] turns a read/write storage volume into a read-only
839 volume. Note that the opposite operation is impossible.
842 (** Module dealing with storage volumes. *)
844 (** {3 Error handling and exceptions} *)
850 | VIR_ERR_INTERNAL_ERROR
853 | VIR_ERR_UNKNOWN_HOST
855 | VIR_ERR_INVALID_CONN
856 | VIR_ERR_INVALID_DOMAIN
857 | VIR_ERR_INVALID_ARG
858 | VIR_ERR_OPERATION_FAILED
860 | VIR_ERR_POST_FAILED
862 | VIR_ERR_SEXPR_SERIAL
873 | VIR_ERR_NO_XENSTORE
874 | VIR_ERR_DRIVER_FULL
875 | VIR_ERR_CALL_FAILED
878 | VIR_ERR_OPERATION_DENIED
879 | VIR_ERR_OPEN_FAILED
880 | VIR_ERR_READ_FAILED
881 | VIR_ERR_PARSE_FAILED
882 | VIR_ERR_CONF_SYNTAX
883 | VIR_ERR_WRITE_FAILED
885 | VIR_ERR_INVALID_NETWORK
886 | VIR_ERR_NETWORK_EXIST
887 | VIR_ERR_SYSTEM_ERROR
889 | VIR_ERR_GNUTLS_ERROR
893 | VIR_ERR_INVALID_MAC
894 | VIR_ERR_AUTH_FAILED
895 | VIR_ERR_INVALID_STORAGE_POOL
896 | VIR_ERR_INVALID_STORAGE_VOL
898 | VIR_ERR_NO_STORAGE_POOL
899 | VIR_ERR_NO_STORAGE_VOL
900 (* ^^ NB: If you add a variant you MUST edit
901 libvirt_c_epilogue.c:MAX_VIR_* *)
902 | VIR_ERR_UNKNOWN of int
903 (** See [<libvirt/virterror.h>] for meaning of these codes. *)
905 val string_of_code : code -> string
924 | VIR_FROM_STATS_LINUX
926 (* ^^ NB: If you add a variant you MUST edit
927 libvirt_c_epilogue.c: MAX_VIR_* *)
928 | VIR_FROM_UNKNOWN of int
929 (** Subsystem / driver which produced the error. *)
931 val string_of_domain : domain -> string
937 (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *)
938 | VIR_ERR_UNKNOWN_LEVEL of int
939 (** No error, a warning or an error. *)
941 val string_of_level : level -> string
944 code : code; (** Error code. *)
945 domain : domain; (** Origin of the error. *)
946 message : string option; (** Human-readable message. *)
947 level : level; (** Error or warning. *)
948 str1 : string option; (** Informational string. *)
949 str2 : string option; (** Informational string. *)
950 str3 : string option; (** Informational string. *)
951 int1 : int32; (** Informational integer. *)
952 int2 : int32; (** Informational integer. *)
954 (** An error object. *)
956 val to_string : t -> string
957 (** Turn the exception into a printable string. *)
959 val get_last_error : unit -> t option
960 val get_last_conn_error : [>`R] Connect.t -> t option
961 (** Get the last error at a global or connection level.
963 Normally you do not need to use these functions because
964 the library automatically turns errors into exceptions.
967 val reset_last_error : unit -> unit
968 val reset_last_conn_error : [>`R] Connect.t -> unit
969 (** Reset the error at a global or connection level.
971 Normally you do not need to use these functions.
974 val no_error : unit -> t
975 (** Creates an empty error message.
977 Normally you do not need to use this function.
980 (** Module dealing with errors. *)
982 exception Virterror of Virterror.t
983 (** This exception can be raised by any library function that detects
984 an error. To get a printable error message, call
985 {!Virterror.to_string} on the content of this exception.
988 exception Not_supported of string
991 [Not_supported "virFoo"]
992 (where [virFoo] is the libvirt function name) if a function is
993 not supported at either compile or run time. This applies to
994 any libvirt function added after version 0.2.1.
996 See also {{:http://libvirt.org/hvsupport.html}http://libvirt.org/hvsupport.html}
999 (** {3 Utility functions} *)
1001 val map_ignore_errors : ('a -> 'b) -> 'a list -> 'b list
1002 (** [map_ignore_errors f xs] calls function [f] for each element of [xs].
1004 This is just like [List.map] except that if [f x] throws a
1005 {!Virterror.t} exception, the error is ignored and [f x]
1006 is not returned in the final list.
1008 This function is primarily useful when dealing with domains which
1009 might 'disappear' asynchronously from the currently running