1 (** OCaml bindings for libvirt. *)
2 (* (C) Copyright 2007-2015 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 {{:https://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 {{:https://libvirt.org/html/libvirt-libvirt-host.html}virConnect*},
62 {{:https://libvirt.org/html/libvirt-libvirt-domain.html}virDomain*}, and
63 {{:https://libvirt.org/html/libvirt-libvirt-network.html}virNetwork*}
64 functions from libvirt.
65 For brevity I usually rename these modules like this:
68 module C = Libvirt.Connect
69 module D = Libvirt.Domain
70 module N = Libvirt.Network
73 To get a connection handle, assuming a Xen hypervisor:
77 let conn = C.connect_readonly ~name ()
80 {3 Example: List running domains}
85 let domains = D.get_domains conn [D.ListActive] in
88 printf "%8d %s\n%!" (D.get_id dom) (D.get_name dom)
92 {3 Example: List inactive domains}
95 let domains = D.get_domains conn [D.ListInactive] in
98 printf "inactive %s\n%!" (D.get_name dom)
102 {3 Example: Print node info}
105 let node_info = C.get_node_info conn in
106 printf "model = %s\n" node_info.C.model;
107 printf "memory = %Ld K\n" node_info.C.memory;
108 printf "cpus = %d\n" node_info.C.cpus;
109 printf "mhz = %d\n" node_info.C.mhz;
110 printf "nodes = %d\n" node_info.C.nodes;
111 printf "sockets = %d\n" node_info.C.sockets;
112 printf "cores = %d\n" node_info.C.cores;
113 printf "threads = %d\n%!" node_info.C.threads;
115 let hostname = C.get_hostname conn in
116 printf "hostname = %s\n%!" hostname;
118 let uri = C.get_uri conn in
119 printf "uri = %s\n%!" uri
125 (** {2 Programming issues}
127 {3 General safety issues}
129 Memory allocation / automatic garbage collection of all libvirt
130 objects should be completely safe. If you find any safety issues
131 or if your pure OCaml program ever segfaults, please contact the author.
133 You can force a libvirt object to be freed early by calling
134 the {!Libvirt.Connect.close} function on the object. This shouldn't
135 affect the safety of garbage collection and should only be used when
136 you want to explicitly free memory. Note that explicitly
137 closing a connection object does nothing if there are still
138 unclosed domain or network objects referencing it.
140 Note that even though you hold open (eg) a domain object, that
141 doesn't mean that the domain (virtual machine) actually exists.
142 The domain could have been shut down or deleted by another user.
143 Thus domain objects can raise odd exceptions at any time.
144 This is just the nature of virtualisation.
146 {3 Backwards and forwards compatibility}
148 OCaml-libvirt requires libvirt version 1.0.2 or later. Future
149 releases of OCaml-libvirt will use newer features of libvirt
150 and therefore will require later versions of libvirt. It is always
151 possible to dynamically link your application against a newer
152 libvirt than OCaml-libvirt was originally compiled against.
154 {3 Get list of domains and domain infos}
156 This is a very common operation, and libvirt supports various
157 different methods to do it. We have hidden the complexity in a
158 flexible {!Libvirt.Domain.get_domains} and
159 {!Libvirt.Domain.get_domains_and_infos} calls which is easy to use and
160 automatically chooses the most efficient method depending on the
161 version of libvirt in use.
165 You can issue multiple concurrent libvirt requests in
166 different threads. However you must follow this rule:
167 Each thread must have its own separate libvirt connection, {i or}
168 you must implement your own mutex scheme to ensure that no
169 two threads can ever make concurrent calls using the same
172 (Note that multithreaded code is not well tested. If you find
173 bugs please report them.)
177 Libvirt requires all callers to call virInitialize before
178 using the library. This is done automatically for you by
179 these bindings when the program starts up, and we believe
180 that the way this is done is safe.
186 (** This is a "raw" UUID, ie. a packed string of bytes. *)
189 (** Type of XML (an uninterpreted string of bytes). Use PXP, expat,
190 xml-light, etc. if you want to do anything useful with the XML.
193 type filename = string
196 val get_version : ?driver:string -> unit -> int * int
197 (** [get_version ()] returns the library version in the first part
198 of the tuple, and [0] in the second part.
200 [get_version ~driver ()] returns the library version in the first
201 part of the tuple, and the version of the driver called [driver]
204 The version numbers are encoded as
205 [major * 1_000_000 + minor * 1000 + release].
208 val uuid_length : int
209 (** Length of packed UUIDs. *)
211 val uuid_string_length : int
212 (** Length of UUID strings. *)
217 {{:https://caml.inria.fr/pub/ml-archives/caml-list/2004/07/80683af867cce6bf8fff273973f70c95.en.html}phantom types}
218 are used to ensure the type-safety of read-only
219 versus read-write connections.
221 All connection/domain/etc. objects are marked with
222 a phantom read-write or read-only type, and trying to
223 pass a read-only object into a function which could
224 mutate the object will cause a compile time error.
226 Each module provides a function like {!Libvirt.Connect.const}
227 to demote a read-write object into a read-only object. The
228 opposite operation is, of course, not allowed.
230 If you want to handle both read-write and read-only
231 connections at runtime, use a variant similar to this:
235 | Read_only of Libvirt.ro Libvirt.Connect.t
236 | Read_write of Libvirt.rw Libvirt.Connect.t
240 (** {3 Forward definitions}
242 These definitions are placed here to avoid the need to
243 use recursive module dependencies.
246 (** {3 Connections} *)
251 (** Connection. Read-only connections have type [ro Connect.t] and
252 read-write connections have type [rw Connect.t].
256 model : string; (** CPU model *)
257 memory : int64; (** memory size in kilobytes *)
258 cpus : int; (** number of active CPUs *)
259 mhz : int; (** expected CPU frequency *)
260 nodes : int; (** number of NUMA nodes (1 = UMA) *)
261 sockets : int; (** number of CPU sockets per node *)
262 cores : int; (** number of cores per socket *)
263 threads : int; (** number of threads per core *)
266 type credential_type =
267 | CredentialUsername (** Identity to act as *)
268 | CredentialAuthname (** Identify to authorize as *)
269 | CredentialLanguage (** RFC 1766 languages, comma separated *)
270 | CredentialCnonce (** client supplies a nonce *)
271 | CredentialPassphrase (** Passphrase secret *)
272 | CredentialEchoprompt (** Challenge response *)
273 | CredentialNoechoprompt (** Challenge response *)
274 | CredentialRealm (** Authentication realm *)
275 | CredentialExternal (** Externally managed credential *)
278 typ : credential_type; (** The type of credential *)
279 prompt : string; (** Prompt to show to user *)
280 challenge : string option; (** Additional challenge to show *)
281 defresult : string option; (** Optional default result *)
285 credtype : credential_type list; (** List of supported credential_type values *)
286 cb : (credential list -> string option list);
287 (** Callback used to collect credentials.
289 The input is a list of all the requested credentials.
291 The function returns a list of all the results from the
292 requested credentials, so the number of results {e must} match
293 the number of input credentials. Each result is optional,
294 and in case it is [None] it means there was no result.
298 val connect : ?name:string -> unit -> rw t
299 (** [connect ~name ()] connects to the hypervisor with URI [name].
301 [connect ()] connects to the default hypervisor.
303 val connect_readonly : ?name:string -> unit -> ro t
304 (** [connect_readonly ~name ()] connects in read-only mode
305 to the hypervisor with URI [name].
307 [connect_readonly ()] connects in read-only mode to the
311 val connect_auth : ?name:string -> auth -> rw t
312 (** [connect_auth ~name auth] connects to the hypervisor with URI
313 [name], using [auth] as authentication handler.
315 [connect_auth auth] connects to the default hypervisor, using
316 [auth] as authentication handler.
318 val connect_auth_readonly : ?name:string -> auth -> ro t
319 (** [connect_auth_readonly ~name auth] connects in read-only mode
320 to the hypervisor with URI [name], using [auth] as authentication
323 [connect_auth_readonly auth] connects in read-only mode to the
324 default hypervisor, using [auth] as authentication handler.
327 val close : [>`R] t -> unit
328 (** [close conn] closes and frees the connection object in memory.
330 The connection is automatically closed if it is garbage
331 collected. This function just forces it to be closed
332 and freed right away.
335 val get_type : [>`R] t -> string
336 (** Returns the name of the driver (hypervisor). *)
338 val get_version : [>`R] t -> int
339 (** Returns the driver version
340 [major * 1_000_000 + minor * 1000 + release]
342 val get_hostname : [>`R] t -> string
343 (** Returns the hostname of the physical server. *)
344 val get_uri : [>`R] t -> string
345 (** Returns the canonical connection URI. *)
346 val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
347 (** Returns the maximum number of virtual CPUs
348 supported by a guest VM of a particular type. *)
349 val list_domains : [>`R] t -> int -> int array
350 (** [list_domains conn max] returns the running domain IDs,
351 up to a maximum of [max] entries.
353 Call {!num_of_domains} first to get a value for [max].
356 {!Libvirt.Domain.get_domains},
357 {!Libvirt.Domain.get_domains_and_infos}.
359 val num_of_domains : [>`R] t -> int
360 (** Returns the number of running domains. *)
361 val get_capabilities : [>`R] t -> xml
362 (** Returns the hypervisor capabilities (as XML). *)
363 val num_of_defined_domains : [>`R] t -> int
364 (** Returns the number of inactive (shutdown) domains. *)
365 val list_defined_domains : [>`R] t -> int -> string array
366 (** [list_defined_domains conn max]
367 returns the names of the inactive domains, up to
368 a maximum of [max] entries.
370 Call {!num_of_defined_domains} first to get a value for [max].
373 {!Libvirt.Domain.get_domains},
374 {!Libvirt.Domain.get_domains_and_infos}.
376 val num_of_networks : [>`R] t -> int
377 (** Returns the number of networks. *)
378 val list_networks : [>`R] t -> int -> string array
379 (** [list_networks conn max]
380 returns the names of the networks, up to a maximum
382 Call {!num_of_networks} first to get a value for [max].
384 val num_of_defined_networks : [>`R] t -> int
385 (** Returns the number of inactive networks. *)
386 val list_defined_networks : [>`R] t -> int -> string array
387 (** [list_defined_networks conn max]
388 returns the names of the inactive networks, up to a maximum
390 Call {!num_of_defined_networks} first to get a value for [max].
393 val num_of_pools : [>`R] t -> int
394 (** Returns the number of storage pools. *)
395 val list_pools : [>`R] t -> int -> string array
396 (** Return list of storage pools. *)
397 val num_of_defined_pools : [>`R] t -> int
398 (** Returns the number of storage pools. *)
399 val list_defined_pools : [>`R] t -> int -> string array
400 (** Return list of storage pools. *)
402 (* The name of this function is inconsistent, but the inconsistency
403 * is really in libvirt itself.
405 val num_of_secrets : [>`R] t -> int
406 (** Returns the number of secrets. *)
407 val list_secrets : [>`R] t -> int -> string array
408 (** Returns the list of secrets. *)
409 val get_node_info : [>`R] t -> node_info
410 (** Return information about the physical server. *)
412 val node_get_free_memory : [> `R] t -> int64
414 [node_get_free_memory conn]
415 returns the amount of free memory (not allocated to any guest)
419 val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array
421 [node_get_cells_free_memory conn start max]
422 returns the amount of free memory on each NUMA cell in kilobytes.
423 [start] is the first cell for which we return free memory.
424 [max] is the maximum number of cells for which we return free memory.
425 Returns an array of up to [max] entries in length.
428 val maxcpus_of_node_info : node_info -> int
429 (** Calculate the total number of CPUs supported (but not necessarily
433 val cpumaplen : int -> int
434 (** Calculate the length (in bytes) required to store the complete
435 CPU map between a single virtual and all physical CPUs of a domain.
438 val use_cpu : bytes -> int -> unit
439 (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
440 val unuse_cpu : bytes -> int -> unit
441 (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
442 val cpu_usable : bytes -> int -> int -> int -> bool
443 (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
444 [cpu] is usable by [vcpu]. *)
446 val set_keep_alive : [>`R] t -> int -> int -> unit
447 (** [set_keep_alive conn interval count] starts sending keepalive
448 messages after [interval] seconds of inactivity and consider the
449 connection to be broken when no response is received after [count]
451 Note: the client has to implement and run an event loop to
452 be able to use keep-alive messages. *)
454 val get_auth_default : unit -> auth
455 (** [get_auth_default ()] returns the default authentication handler
459 external const : [>`R] t -> ro t = "%identity"
460 (** [const conn] turns a read/write connection into a read-only
461 connection. Note that the opposite operation is impossible.
464 (** Module dealing with connections. [Connect.t] is the
465 connection object. *)
472 (** Domain handle. Read-only handles have type [ro Domain.t] and
473 read-write handles have type [rw Domain.t].
477 | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
478 | InfoShutdown | InfoShutoff | InfoCrashed | InfoPMSuspended
481 state : state; (** running state *)
482 max_mem : int64; (** maximum memory in kilobytes *)
483 memory : int64; (** memory used in kilobytes *)
484 nr_virt_cpu : int; (** number of virtual CPUs *)
485 cpu_time : int64; (** CPU time used in nanoseconds *)
488 type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
491 number : int; (** virtual CPU number *)
492 vcpu_state : vcpu_state; (** state *)
493 vcpu_time : int64; (** CPU time used in nanoseconds *)
494 cpu : int; (** real CPU number, -1 if offline *)
497 type domain_create_flag =
498 | START_PAUSED (** Launch guest in paused state *)
499 | START_AUTODESTROY (** Automatically kill guest on close *)
500 | START_BYPASS_CACHE (** Avoid filesystem cache pollution *)
501 | START_FORCE_BOOT (** Discard any managed save *)
502 | START_VALIDATE (** Validate XML against schema *)
504 type sched_param = string * sched_param_value
505 and sched_param_value =
506 | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
507 | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
508 | SchedFieldFloat of float | SchedFieldBool of bool
510 type typed_param = string * typed_param_value
511 and typed_param_value =
512 | TypedFieldInt32 of int32 | TypedFieldUInt32 of int32
513 | TypedFieldInt64 of int64 | TypedFieldUInt64 of int64
514 | TypedFieldFloat of float | TypedFieldBool of bool
515 | TypedFieldString of string
517 type migrate_flag = Live
519 type memory_flag = Virtual
534 type interface_stats = {
545 type get_all_domain_stats_flag =
546 | GetAllDomainsStatsActive
547 | GetAllDomainsStatsInactive
548 | GetAllDomainsStatsOther
549 | GetAllDomainsStatsPaused
550 | GetAllDomainsStatsPersistent
551 | GetAllDomainsStatsRunning
552 | GetAllDomainsStatsShutoff
553 | GetAllDomainsStatsTransient
554 | GetAllDomainsStatsBacking
555 | GetAllDomainsStatsEnforceStats
558 | StatsState | StatsCpuTotal | StatsBalloon | StatsVcpu
559 | StatsInterface | StatsBlock | StatsPerf
561 type domain_stats_record = {
563 params : typed_param array;
567 | XmlSecure (** dump security sensitive information too *)
568 | XmlInactive (** dump inactive domain information *)
569 | XmlUpdateCPU (** update guest CPU requirements according to host CPU *)
570 | XmlMigratable (** dump XML suitable for migration *)
572 val max_peek : [>`R] t -> int
573 (** Maximum size supported by the {!block_peek} and {!memory_peek}
574 functions. If you want to peek more than this then you must
575 break your request into chunks. *)
577 val create_linux : [>`W] Connect.t -> xml -> rw t
578 (** Create a new guest domain (not necessarily a Linux one)
580 @deprecated Use {!create_xml} instead.
582 val create_xml : [>`W] Connect.t -> xml -> domain_create_flag list -> rw t
583 (** Create a new guest domain from the given XML. *)
584 val lookup_by_id : 'a Connect.t -> int -> 'a t
585 (** Lookup a domain by ID. *)
586 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
587 (** Lookup a domain by UUID. This uses the packed byte array UUID. *)
588 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
589 (** Lookup a domain by (string) UUID. *)
590 val lookup_by_name : 'a Connect.t -> string -> 'a t
591 (** Lookup a domain by name. *)
592 val destroy : [>`W] t -> unit
593 (** Abruptly destroy a domain. *)
594 val free : [>`R] t -> unit
595 (** [free domain] frees the domain object in memory.
597 The domain object is automatically freed if it is garbage
598 collected. This function just forces it to be freed right
602 val suspend : [>`W] t -> unit
603 (** Suspend a domain. *)
604 val resume : [>`W] t -> unit
605 (** Resume a domain. *)
606 val save : [>`W] t -> filename -> unit
607 (** Suspend a domain, then save it to the file. *)
608 val restore : [>`W] Connect.t -> filename -> unit
609 (** Restore a domain from a file. *)
610 val core_dump : [>`W] t -> filename -> unit
611 (** Force a domain to core dump to the named file. *)
612 val shutdown : [>`W] t -> unit
613 (** Shutdown a domain. *)
614 val reboot : [>`W] t -> unit
615 (** Reboot a domain. *)
616 val get_name : [>`R] t -> string
617 (** Get the domain name. *)
618 val get_uuid : [>`R] t -> uuid
619 (** Get the domain UUID (as a packed byte array). *)
620 val get_uuid_string : [>`R] t -> string
621 (** Get the domain UUID (as a printable string). *)
622 val get_id : [>`R] t -> int
623 (** [get_id dom] returns the ID of the domain. In most cases
624 this returns [-1] if the domain is not running. *)
625 val get_os_type : [>`R] t -> string
626 (** Get the operating system type. *)
627 val get_max_memory : [>`R] t -> int64
628 (** Get the maximum memory allocation. *)
629 val set_max_memory : [>`W] t -> int64 -> unit
630 (** Set the maximum memory allocation. *)
631 val set_memory : [>`W] t -> int64 -> unit
632 (** Set the normal memory allocation. *)
633 val get_info : [>`R] t -> info
634 (** Get information about a domain. *)
635 val get_xml_desc : [>`R] t -> xml
636 (** Get the XML description of a domain. *)
637 val get_xml_desc_flags : [>`W] t -> xml_desc_flag list -> xml
638 (** Get the XML description of a domain, with the possibility
640 val get_scheduler_type : [>`R] t -> string * int
641 (** Get the scheduler type. *)
642 val get_scheduler_parameters : [>`R] t -> int -> sched_param array
643 (** Get the array of scheduler parameters. *)
644 val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
645 (** Set the array of scheduler parameters. *)
646 val define_xml : [>`W] Connect.t -> xml -> rw t
647 (** Define a new domain (but don't start it up) from the XML. *)
648 val undefine : [>`W] t -> unit
649 (** Undefine a domain - removes its configuration. *)
650 val create : [>`W] t -> unit
651 (** Launch a defined (inactive) domain. *)
652 val get_autostart : [>`R] t -> bool
653 (** Get the autostart flag for a domain. *)
654 val set_autostart : [>`W] t -> bool -> unit
655 (** Set the autostart flag for a domain. *)
656 val set_vcpus : [>`W] t -> int -> unit
657 (** Change the number of vCPUs available to a domain. *)
658 val pin_vcpu : [>`W] t -> int -> string -> unit
659 (** [pin_vcpu dom vcpu bitmap] pins a domain vCPU to a bitmap of physical
660 CPUs. See the libvirt documentation for details of the
661 layout of the bitmap. *)
662 val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
663 (** [get_vcpus dom maxinfo maplen] returns the pinning information
664 for a domain. See the libvirt documentation for details
665 of the array and bitmap returned from this function.
667 val get_cpu_stats : [>`R] t -> typed_param list array
668 (** [get_pcpu_stats dom] returns the physical CPU stats
669 for a domain. See the libvirt documentation for details.
671 val get_max_vcpus : [>`R] t -> int
672 (** Returns the maximum number of vCPUs supported for this domain. *)
673 val attach_device : [>`W] t -> xml -> unit
674 (** Attach a device (described by the device XML) to a domain. *)
675 val detach_device : [>`W] t -> xml -> unit
676 (** Detach a device (described by the device XML) from a domain. *)
678 val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
679 ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
680 (** [migrate dom dconn flags ()] migrates a domain to a
681 destination host described by [dconn].
683 The optional flag [?dname] is used to rename the domain.
685 The optional flag [?uri] is used to route the migration.
687 The optional flag [?bandwidth] is used to limit the bandwidth
688 used for migration (in Mbps). *)
690 val block_stats : [>`R] t -> string -> block_stats
691 (** Returns block device stats. *)
692 val interface_stats : [>`R] t -> string -> interface_stats
693 (** Returns network interface stats. *)
695 val block_peek : [>`W] t -> string -> int64 -> int -> string -> int -> unit
696 (** [block_peek dom path offset size buf boff] reads [size] bytes at
697 [offset] in the domain's [path] block device.
699 If successful then the data is written into [buf] starting
700 at offset [boff], for [size] bytes.
702 See also {!max_peek}. *)
703 val memory_peek : [>`W] t -> memory_flag list -> int64 -> int ->
704 string -> int -> unit
705 (** [memory_peek dom Virtual offset size] reads [size] bytes
706 at [offset] in the domain's virtual memory.
708 If successful then the data is written into [buf] starting
709 at offset [boff], for [size] bytes.
711 See also {!max_peek}. *)
713 external get_all_domain_stats : [>`R] Connect.t -> stats_type list -> get_all_domain_stats_flag list -> domain_stats_record array = "ocaml_libvirt_domain_get_all_domain_stats"
714 (** [get_all_domain_stats conn stats flags] allows you to read
715 all stats across multiple/all domains in a single call.
717 See the libvirt documentation for
718 [virConnectGetAllDomainStats]. *)
720 external const : [>`R] t -> ro t = "%identity"
721 (** [const dom] turns a read/write domain handle into a read-only
722 domain handle. Note that the opposite operation is impossible.
725 val get_domains : ([>`R] as 'a) Connect.t -> list_flag list -> 'a t list
726 (** Get the active and/or inactive domains using the most
727 efficient method available.
730 {!get_domains_and_infos},
731 {!Connect.list_domains},
732 {!Connect.list_defined_domains}.
735 val get_domains_and_infos : ([>`R] as 'a) Connect.t -> list_flag list ->
737 (** This gets the active and/or inactive domains and the
738 domain info for each one using the most efficient
743 {!Connect.list_domains},
744 {!Connect.list_defined_domains},
749 (** Module dealing with domains. [Domain.t] is the
757 | `Added (** Newly created config file *)
758 | `Updated (** Changed config file *)
762 val to_string: t -> string
765 module Undefined : sig
767 | `Removed (** Deleted the config file *)
771 val to_string: t -> string
776 | `Booted (** Normal startup from boot *)
777 | `Migrated (** Incoming migration from another host *)
778 | `Restored (** Restored from a state file *)
779 | `FromSnapshot (** Restored from snapshot *)
780 | `Wakeup (** Started due to wakeup event *)
784 val to_string: t -> string
787 module Suspended : sig
789 | `Paused (** Normal suspend due to admin pause *)
790 | `Migrated (** Suspended for offline migration *)
791 | `IOError (** Suspended due to a disk I/O error *)
792 | `Watchdog (** Suspended due to a watchdog firing *)
793 | `Restored (** Restored from paused state file *)
794 | `FromSnapshot (** Restored from paused snapshot *)
795 | `APIError (** suspended after failure during libvirt API call *)
799 val to_string: t -> string
804 | `Unpaused (** Normal resume due to admin unpause *)
805 | `Migrated (** Resumed for completion of migration *)
806 | `FromSnapshot (** Resumed from snapshot *)
810 val to_string: t -> string
815 | `Shutdown (** Normal shutdown *)
816 | `Destroyed (** Forced poweroff from host *)
817 | `Crashed (** Guest crashed *)
818 | `Migrated (** Migrated off to another host *)
819 | `Saved (** Saved to a state file *)
820 | `Failed (** Host emulator/mgmt failed *)
821 | `FromSnapshot (** offline snapshot loaded *)
825 val to_string: t -> string
828 module PM_suspended : sig
830 | `Memory (** Guest was PM suspended to memory *)
831 | `Disk (** Guest was PM suspended to disk *)
835 val to_string: t -> string
838 module Lifecycle : sig
840 | `Defined of Defined.t
841 | `Undefined of Undefined.t
842 | `Started of Started.t
843 | `Suspended of Suspended.t
844 | `Resumed of Resumed.t
845 | `Stopped of Stopped.t
846 | `Shutdown (* no detail defined yet *)
847 | `PMSuspended of PM_suspended.t
851 val to_string: t -> string
857 val to_string: t -> string
860 module Rtc_change : sig
863 val to_string: t -> string
866 module Watchdog : sig
868 | `None (** No action, watchdog ignored *)
869 | `Pause (** Guest CPUs are paused *)
870 | `Reset (** Guest CPUs are reset *)
871 | `Poweroff (** Guest is forcably powered off *)
872 | `Shutdown (** Guest is requested to gracefully shutdown *)
873 | `Debug (** No action, a debug message logged *)
874 | `Unknown of int (** newer libvirt *)
877 val to_string: t -> string
880 module Io_error : sig
881 (** Represents both IOError and IOErrorReason *)
883 | `None (** No action, IO error ignored *)
884 | `Pause (** Guest CPUs are paused *)
885 | `Report (** IO error reported to guest OS *)
886 | `Unknown of int (** newer libvirt *)
890 src_path: string option; (** The host file on which the I/O error occurred *)
891 dev_alias: string option; (** The guest device alias associated with the path *)
892 action: action; (** The action that is to be taken due to the IO error *)
893 reason: string option; (** The cause of the IO error *)
896 val to_string: t -> string
899 module Graphics_address : sig
901 | `Ipv4 (** IPv4 address *)
902 | `Ipv6 (** IPv6 address *)
903 | `Unix (** UNIX socket path *)
904 | `Unknown of int (** newer libvirt *)
908 family: family; (** Address family *)
909 node: string option; (** Address of node (eg IP address, or UNIX path *)
910 service: string option; (** Service name/number (eg TCP port, or NULL) *)
913 val to_string: t -> string
916 module Graphics_subject : sig
918 ty: string option; (** Type of identity *)
919 name: string option; (** Identity value *)
922 type t = identity list
924 val to_string: t -> string
927 module Graphics : sig
929 | `Connect (** Initial socket connection established *)
930 | `Initialize (** Authentication & setup completed *)
931 | `Disconnect (** Final socket disconnection *)
932 | `Unknown of int (** newer libvirt *)
936 phase: phase; (** the phase of the connection *)
937 local: Graphics_address.t; (** the local server address *)
938 remote: Graphics_address.t; (** the remote client address *)
939 auth_scheme: string option; (** the authentication scheme activated *)
940 subject: Graphics_subject.t; (** the authenticated subject (user) *)
943 val to_string: t -> string
946 module Control_error : sig
949 val to_string: t -> string
952 module Block_job : sig
954 | `KnownUnknown (** explicitly named UNKNOWN in the spec *)
970 disk: string option; (** fully-qualified name of the affected disk *)
971 ty: ty; (** type of block job *)
972 status: status; (** final status of the operation *)
975 val to_string: t -> string
978 module Disk_change : sig
985 old_src_path: string option; (** old source path *)
986 new_src_path: string option; (** new source path *)
987 dev_alias: string option; (** device alias name *)
988 reason: reason; (** reason why this callback was called *)
991 val to_string: t -> string
994 module Tray_change : sig
1002 dev_alias: string option; (** device alias *)
1003 reason: reason; (** why the tray status was changed *)
1006 val to_string: t -> string
1009 module PM_wakeup : sig
1016 val to_string: t -> string
1019 module PM_suspend : sig
1026 val to_string: t -> string
1029 module Balloon_change : sig
1032 val to_string: t -> string
1035 module PM_suspend_disk : sig
1042 val to_string: t -> string
1047 | Lifecycle of ([`R] Domain.t -> Lifecycle.t -> unit)
1048 | Reboot of ([`R] Domain.t -> Reboot.t -> unit)
1049 | RtcChange of ([`R] Domain.t -> Rtc_change.t -> unit)
1050 | Watchdog of ([`R] Domain.t -> Watchdog.t -> unit)
1051 | IOError of ([`R] Domain.t -> Io_error.t -> unit)
1052 | Graphics of ([`R] Domain.t -> Graphics.t -> unit)
1053 | IOErrorReason of ([`R] Domain.t -> Io_error.t -> unit)
1054 | ControlError of ([`R] Domain.t -> Control_error.t -> unit)
1055 | BlockJob of ([`R] Domain.t -> Block_job.t -> unit)
1056 | DiskChange of ([`R] Domain.t -> Disk_change.t -> unit)
1057 | TrayChange of ([`R] Domain.t -> Tray_change.t -> unit)
1058 | PMWakeUp of ([`R] Domain.t -> PM_wakeup.t -> unit)
1059 | PMSuspend of ([`R] Domain.t -> PM_suspend.t -> unit)
1060 | BalloonChange of ([`R] Domain.t -> Balloon_change.t -> unit)
1061 | PMSuspendDisk of ([`R] Domain.t -> PM_suspend_disk.t -> unit)
1063 (** type of a registered call back function *)
1065 val register_default_impl : unit -> unit
1066 (** Registers the default event loop based on poll(). This
1067 must be done before connections are opened.
1069 Once registered call run_default_impl in a loop. *)
1071 val run_default_impl : unit -> unit
1072 (** Runs one iteration of the event loop. Applications will
1073 generally want to have a thread which invokes this in an
1077 (** an individual event registration *)
1079 val register_any : 'a Connect.t -> ?dom:'a Domain.t -> callback -> callback_id
1080 (** [register_any con ?dom callback] registers [callback]
1081 to receive notification of arbitrary domain events. Return
1082 a registration id which can be used in [deregister_any].
1084 If [?dom] is [None] then register for this kind of event on
1085 all domains. If [dom] is [Some d] then register for this
1086 kind of event only on [d].
1089 val deregister_any : 'a Connect.t -> callback_id -> unit
1090 (** [deregister_any con id] deregisters the previously registered
1091 callback with id [id]. *)
1094 (** an individual timer event *)
1096 val add_timeout : 'a Connect.t -> int -> (unit -> unit) -> timer_id
1097 (** [add_timeout con ms cb] registers [cb] as a timeout callback
1098 which will be called every [ms] milliseconds *)
1100 val remove_timeout : 'a Connect.t -> timer_id -> unit
1101 (** [remove_timeout con t] deregisters timeout callback [t]. *)
1104 (** Module dealing with events generated by domain
1112 (** Network handle. Read-only handles have type [ro Network.t] and
1113 read-write handles have type [rw Network.t].
1116 val lookup_by_name : 'a Connect.t -> string -> 'a t
1117 (** Lookup a network by name. *)
1118 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
1119 (** Lookup a network by (packed) UUID. *)
1120 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
1121 (** Lookup a network by UUID string. *)
1122 val create_xml : [>`W] Connect.t -> xml -> rw t
1123 (** Create a network. *)
1124 val define_xml : [>`W] Connect.t -> xml -> rw t
1125 (** Define but don't activate a network. *)
1126 val undefine : [>`W] t -> unit
1127 (** Undefine configuration of a network. *)
1128 val create : [>`W] t -> unit
1129 (** Start up a defined (inactive) network. *)
1130 val destroy : [>`W] t -> unit
1131 (** Destroy a network. *)
1132 val free : [>`R] t -> unit
1133 (** [free network] frees the network object in memory.
1135 The network object is automatically freed if it is garbage
1136 collected. This function just forces it to be freed right
1140 val get_name : [>`R] t -> string
1141 (** Get network name. *)
1142 val get_uuid : [>`R] t -> uuid
1143 (** Get network packed UUID. *)
1144 val get_uuid_string : [>`R] t -> string
1145 (** Get network UUID as a printable string. *)
1146 val get_xml_desc : [>`R] t -> xml
1147 (** Get XML description of a network. *)
1148 val get_bridge_name : [>`R] t -> string
1149 (** Get bridge device name of a network. *)
1150 val get_autostart : [>`R] t -> bool
1151 (** Get the autostart flag for a network. *)
1152 val set_autostart : [>`W] t -> bool -> unit
1153 (** Set the autostart flag for a network. *)
1155 external const : [>`R] t -> ro t = "%identity"
1156 (** [const network] turns a read/write network handle into a read-only
1157 network handle. Note that the opposite operation is impossible.
1160 (** Module dealing with networks. [Network.t] is the
1163 (** {3 Storage pools} *)
1168 (** Storage pool handle. *)
1170 type pool_state = Inactive | Building | Running | Degraded | Inaccessible
1171 (** State of the storage pool. *)
1173 type pool_build_flags = New | Repair | Resize
1174 (** Flags for creating a storage pool. *)
1176 type pool_delete_flags = Normal | Zeroed
1177 (** Flags for deleting a storage pool. *)
1180 state : pool_state; (** Pool state. *)
1181 capacity : int64; (** Logical size in bytes. *)
1182 allocation : int64; (** Currently allocated in bytes. *)
1183 available : int64; (** Remaining free space bytes. *)
1186 val lookup_by_name : 'a Connect.t -> string -> 'a t
1187 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
1188 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
1189 (** Look up a storage pool by name, UUID or UUID string. *)
1191 val create_xml : [>`W] Connect.t -> xml -> rw t
1192 (** Create a storage pool. *)
1193 val define_xml : [>`W] Connect.t -> xml -> rw t
1194 (** Define but don't activate a storage pool. *)
1195 val build : [>`W] t -> pool_build_flags -> unit
1196 (** Build a storage pool. *)
1197 val undefine : [>`W] t -> unit
1198 (** Undefine configuration of a storage pool. *)
1199 val create : [>`W] t -> unit
1200 (** Start up a defined (inactive) storage pool. *)
1201 val destroy : [>`W] t -> unit
1202 (** Destroy a storage pool. *)
1203 val delete : [>`W] t -> unit
1204 (** Delete a storage pool. *)
1205 val free : [>`R] t -> unit
1206 (** Free a storage pool object in memory.
1208 The storage pool object is automatically freed if it is garbage
1209 collected. This function just forces it to be freed right
1212 val refresh : [`R] t -> unit
1213 (** Refresh the list of volumes in the storage pool. *)
1215 val get_name : [`R] t -> string
1216 (** Name of the pool. *)
1217 val get_uuid : [`R] t -> uuid
1218 (** Get the UUID (as a packed byte array). *)
1219 val get_uuid_string : [`R] t -> string
1220 (** Get the UUID (as a printable string). *)
1221 val get_info : [`R] t -> pool_info
1222 (** Get information about the pool. *)
1223 val get_xml_desc : [`R] t -> xml
1224 (** Get the XML description. *)
1225 val get_autostart : [`R] t -> bool
1226 (** Get the autostart flag for the storage pool. *)
1227 val set_autostart : [>`W] t -> bool -> unit
1228 (** Set the autostart flag for the storage pool. *)
1230 val num_of_volumes : [`R] t -> int
1231 (** Returns the number of storage volumes within the storage pool. *)
1232 val list_volumes : [`R] t -> int -> string array
1233 (** Return list of storage volumes. *)
1235 external const : [>`R] t -> ro t = "%identity"
1236 (** [const conn] turns a read/write storage pool into a read-only
1237 pool. Note that the opposite operation is impossible.
1240 (** Module dealing with storage pools. *)
1242 (** {3 Storage volumes} *)
1247 (** Storage volume handle. *)
1249 type vol_type = File | Block | Dir | Network | NetDir | Ploop
1250 (** Type of a storage volume. *)
1252 type vol_delete_flags = Normal | Zeroed
1253 (** Flags for deleting a storage volume. *)
1256 typ : vol_type; (** Type of storage volume. *)
1257 capacity : int64; (** Logical size in bytes. *)
1258 allocation : int64; (** Currently allocated in bytes. *)
1261 val lookup_by_name : 'a Pool.t -> string -> 'a t
1262 val lookup_by_key : 'a Connect.t -> string -> 'a t
1263 val lookup_by_path : 'a Connect.t -> string -> 'a t
1264 (** Look up a storage volume by name, key or path volume. *)
1266 val pool_of_volume : 'a t -> 'a Pool.t
1267 (** Get the storage pool containing this volume. *)
1269 val get_name : [`R] t -> string
1270 (** Name of the volume. *)
1271 val get_key : [`R] t -> string
1272 (** Key of the volume. *)
1273 val get_path : [`R] t -> string
1274 (** Path of the volume. *)
1275 val get_info : [`R] t -> vol_info
1276 (** Get information about the storage volume. *)
1277 val get_xml_desc : [`R] t -> xml
1278 (** Get the XML description. *)
1280 val create_xml : [>`W] Pool.t -> xml -> unit
1281 (** Create a storage volume. *)
1282 val delete : [>`W] t -> vol_delete_flags -> unit
1283 (** Delete a storage volume. *)
1284 val free : [>`R] t -> unit
1285 (** Free a storage volume object in memory.
1287 The storage volume object is automatically freed if it is garbage
1288 collected. This function just forces it to be freed right
1292 external const : [>`R] t -> ro t = "%identity"
1293 (** [const conn] turns a read/write storage volume into a read-only
1294 volume. Note that the opposite operation is impossible.
1297 (** Module dealing with storage volumes. *)
1304 (** Secret handle. *)
1306 type secret_usage_type =
1312 (** Usage type of a secret. *)
1314 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
1315 (** Lookup a secret by UUID. This uses the packed byte array UUID. *)
1316 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
1317 (** Lookup a secret by (string) UUID. *)
1318 val lookup_by_usage : 'a Connect.t -> secret_usage_type -> string -> 'a t
1319 (** Lookup a secret by usage type, and usage ID. *)
1321 val define_xml : [>`W] Connect.t -> xml -> rw t
1322 (** Define a secret. *)
1324 val get_uuid : [>`R] t -> uuid
1325 (** Get the UUID (as a packed byte array) of the secret. *)
1326 val get_uuid_string : [>`R] t -> string
1327 (** Get the UUID (as a printable string) of the secret. *)
1328 val get_usage_type : [>`R] t -> secret_usage_type
1329 (** Get the usage type of the secret. *)
1330 val get_usage_id : [>`R] t -> string
1331 (** Get the usage ID of the secret. *)
1332 val get_xml_desc : [>`R] t -> xml
1333 (** Get the XML description. *)
1335 val set_value : [>`W] t -> bytes -> unit
1336 (** Set a new value for the secret. *)
1337 val get_value : [>`R] t -> bytes
1338 (** Get the value of the secret. *)
1340 val undefine : [>`W] t -> unit
1341 (** Undefine a secret. *)
1343 val free : [>`R] t -> unit
1344 (** Free a secret object in memory.
1346 The secret object is automatically freed if it is garbage
1347 collected. This function just forces it to be freed right
1351 external const : [>`R] t -> ro t = "%identity"
1352 (** [const conn] turns a read/write secret into a read-only
1353 secret. Note that the opposite operation is impossible.
1356 (** Module dealing with secrets. *)
1358 (** {3 Error handling and exceptions} *)
1364 | VIR_ERR_INTERNAL_ERROR
1366 | VIR_ERR_NO_SUPPORT
1367 | VIR_ERR_UNKNOWN_HOST
1368 | VIR_ERR_NO_CONNECT
1369 | VIR_ERR_INVALID_CONN
1370 | VIR_ERR_INVALID_DOMAIN
1371 | VIR_ERR_INVALID_ARG
1372 | VIR_ERR_OPERATION_FAILED
1373 | VIR_ERR_GET_FAILED
1374 | VIR_ERR_POST_FAILED
1375 | VIR_ERR_HTTP_ERROR
1376 | VIR_ERR_SEXPR_SERIAL
1387 | VIR_ERR_NO_XENSTORE
1388 | VIR_ERR_DRIVER_FULL
1389 | VIR_ERR_CALL_FAILED
1392 | VIR_ERR_OPERATION_DENIED
1393 | VIR_ERR_OPEN_FAILED
1394 | VIR_ERR_READ_FAILED
1395 | VIR_ERR_PARSE_FAILED
1396 | VIR_ERR_CONF_SYNTAX
1397 | VIR_ERR_WRITE_FAILED
1398 | VIR_ERR_XML_DETAIL
1399 | VIR_ERR_INVALID_NETWORK
1400 | VIR_ERR_NETWORK_EXIST
1401 | VIR_ERR_SYSTEM_ERROR
1403 | VIR_ERR_GNUTLS_ERROR
1404 | VIR_WAR_NO_NETWORK
1406 | VIR_ERR_NO_NETWORK
1407 | VIR_ERR_INVALID_MAC
1408 | VIR_ERR_AUTH_FAILED
1409 | VIR_ERR_INVALID_STORAGE_POOL
1410 | VIR_ERR_INVALID_STORAGE_VOL
1411 | VIR_WAR_NO_STORAGE
1412 | VIR_ERR_NO_STORAGE_POOL
1413 | VIR_ERR_NO_STORAGE_VOL
1415 | VIR_ERR_INVALID_NODE_DEVICE
1416 | VIR_ERR_NO_NODE_DEVICE
1417 | VIR_ERR_NO_SECURITY_MODEL
1418 | VIR_ERR_OPERATION_INVALID
1419 | VIR_WAR_NO_INTERFACE
1420 | VIR_ERR_NO_INTERFACE
1421 | VIR_ERR_INVALID_INTERFACE
1422 | VIR_ERR_MULTIPLE_INTERFACES
1423 | VIR_WAR_NO_NWFILTER
1424 | VIR_ERR_INVALID_NWFILTER
1425 | VIR_ERR_NO_NWFILTER
1426 | VIR_ERR_BUILD_FIREWALL
1428 | VIR_ERR_INVALID_SECRET
1430 | VIR_ERR_CONFIG_UNSUPPORTED
1431 | VIR_ERR_OPERATION_TIMEOUT
1432 | VIR_ERR_MIGRATE_PERSIST_FAILED
1433 | VIR_ERR_HOOK_SCRIPT_FAILED
1434 | VIR_ERR_INVALID_DOMAIN_SNAPSHOT
1435 | VIR_ERR_NO_DOMAIN_SNAPSHOT
1436 | VIR_ERR_INVALID_STREAM
1437 | VIR_ERR_ARGUMENT_UNSUPPORTED
1438 | VIR_ERR_STORAGE_PROBE_FAILED
1439 | VIR_ERR_STORAGE_POOL_BUILT
1440 | VIR_ERR_SNAPSHOT_REVERT_RISKY
1441 | VIR_ERR_OPERATION_ABORTED
1442 | VIR_ERR_AUTH_CANCELLED
1443 | VIR_ERR_NO_DOMAIN_METADATA
1444 | VIR_ERR_MIGRATE_UNSAFE
1446 | VIR_ERR_BLOCK_COPY_ACTIVE
1447 | VIR_ERR_OPERATION_UNSUPPORTED
1449 | VIR_ERR_AGENT_UNRESPONSIVE
1450 | VIR_ERR_RESOURCE_BUSY
1451 | VIR_ERR_ACCESS_DENIED
1452 | VIR_ERR_DBUS_SERVICE
1453 | VIR_ERR_STORAGE_VOL_EXIST
1454 | VIR_ERR_CPU_INCOMPATIBLE
1455 | VIR_ERR_XML_INVALID_SCHEMA
1456 | VIR_ERR_MIGRATE_FINISH_OK
1457 | VIR_ERR_AUTH_UNAVAILABLE
1460 | VIR_ERR_AGENT_UNSYNCED
1462 | VIR_ERR_DEVICE_MISSING
1463 | VIR_ERR_INVALID_NWFILTER_BINDING
1464 | VIR_ERR_NO_NWFILTER_BINDING
1465 (* ^^ NB: If you add a variant you MUST edit
1466 libvirt_c_epilogue.c:MAX_VIR_* *)
1467 | VIR_ERR_UNKNOWN of int (** Other error, not handled with existing values. *)
1468 (** See [<libvirt/virterror.h>] for meaning of these codes. *)
1470 val string_of_code : code -> string
1489 | VIR_FROM_STATS_LINUX
1496 | VIR_FROM_XEN_INOTIFY
1499 | VIR_FROM_INTERFACE
1508 | VIR_FROM_DOMAIN_SNAPSHOT
1517 | VIR_FROM_CAPABILITIES
1521 | VIR_FROM_PARALLELS
1524 | VIR_FROM_LOCKSPACE
1541 (* ^^ NB: If you add a variant you MUST edit
1542 libvirt_c_epilogue.c: MAX_VIR_* *)
1543 | VIR_FROM_UNKNOWN of int (** Other domain, not handled with existing values. *)
1544 (** Subsystem / driver which produced the error. *)
1546 val string_of_domain : domain -> string
1552 (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *)
1553 | VIR_ERR_UNKNOWN_LEVEL of int (** Other level, not handled with existing values. *)
1554 (** No error, a warning or an error. *)
1556 val string_of_level : level -> string
1559 code : code; (** Error code. *)
1560 domain : domain; (** Origin of the error. *)
1561 message : string option; (** Human-readable message. *)
1562 level : level; (** Error or warning. *)
1563 str1 : string option; (** Informational string. *)
1564 str2 : string option; (** Informational string. *)
1565 str3 : string option; (** Informational string. *)
1566 int1 : int32; (** Informational integer. *)
1567 int2 : int32; (** Informational integer. *)
1569 (** An error object. *)
1571 val to_string : t -> string
1572 (** Turn the exception into a printable string. *)
1574 val get_last_error : unit -> t option
1575 val get_last_conn_error : [>`R] Connect.t -> t option
1576 (** Get the last error at a global or connection level.
1578 Normally you do not need to use these functions because
1579 the library automatically turns errors into exceptions.
1582 val reset_last_error : unit -> unit
1583 val reset_last_conn_error : [>`R] Connect.t -> unit
1584 (** Reset the error at a global or connection level.
1586 Normally you do not need to use these functions.
1589 val no_error : unit -> t
1590 (** Creates an empty error message.
1592 Normally you do not need to use this function.
1595 (** Module dealing with errors. *)
1597 exception Virterror of Virterror.t
1598 (** This exception can be raised by any library function that detects
1599 an error. To get a printable error message, call
1600 {!Virterror.to_string} on the content of this exception.
1603 exception Not_supported of string
1606 [Not_supported "virFoo"]
1607 (where [virFoo] is the libvirt function name) if a function is
1608 not supported at either compile or run time. This applies to
1609 any libvirt function added after version 0.2.1.
1611 See also {{:https://libvirt.org/hvsupport.html}https://libvirt.org/hvsupport.html}
1614 (** {3 Utility functions} *)
1616 val map_ignore_errors : ('a -> 'b) -> 'a list -> 'b list
1617 (** [map_ignore_errors f xs] calls function [f] for each element of [xs].
1619 This is just like [List.map] except that if [f x] throws a
1620 {!Virterror.t} exception, the error is ignored and [f x]
1621 is not returned in the final list.
1623 This function is primarily useful when dealing with domains which
1624 might 'disappear' asynchronously from the currently running