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 [close] function on the object. This shouldn't affect
135 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 1,000,000 * major + 1,000 * minor + 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 val connect_readonly : ?name:string -> unit -> ro t
300 (** [connect ~name ()] connects to the hypervisor with URI [name].
302 [connect ()] connects to the default hypervisor.
304 [connect_readonly] is the same but connects in read-only mode.
307 val connect_auth : ?name:string -> auth -> rw t
308 val connect_auth_readonly : ?name:string -> auth -> ro t
310 val close : [>`R] t -> unit
311 (** [close conn] closes and frees the connection object in memory.
313 The connection is automatically closed if it is garbage
314 collected. This function just forces it to be closed
315 and freed right away.
318 val get_type : [>`R] t -> string
319 (** Returns the name of the driver (hypervisor). *)
321 val get_version : [>`R] t -> int
322 (** Returns the driver version
323 [major * 1_000_000 + minor * 1000 + release]
325 val get_hostname : [>`R] t -> string
326 (** Returns the hostname of the physical server. *)
327 val get_uri : [>`R] t -> string
328 (** Returns the canonical connection URI. *)
329 val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
330 (** Returns the maximum number of virtual CPUs
331 supported by a guest VM of a particular type. *)
332 val list_domains : [>`R] t -> int -> int array
333 (** [list_domains conn max] returns the running domain IDs,
334 up to a maximum of [max] entries.
336 Call {!num_of_domains} first to get a value for [max].
339 {!Libvirt.Domain.get_domains},
340 {!Libvirt.Domain.get_domains_and_infos}.
342 val num_of_domains : [>`R] t -> int
343 (** Returns the number of running domains. *)
344 val get_capabilities : [>`R] t -> xml
345 (** Returns the hypervisor capabilities (as XML). *)
346 val num_of_defined_domains : [>`R] t -> int
347 (** Returns the number of inactive (shutdown) domains. *)
348 val list_defined_domains : [>`R] t -> int -> string array
349 (** [list_defined_domains conn max]
350 returns the names of the inactive domains, up to
351 a maximum of [max] entries.
353 Call {!num_of_defined_domains} first to get a value for [max].
356 {!Libvirt.Domain.get_domains},
357 {!Libvirt.Domain.get_domains_and_infos}.
359 val num_of_networks : [>`R] t -> int
360 (** Returns the number of networks. *)
361 val list_networks : [>`R] t -> int -> string array
362 (** [list_networks conn max]
363 returns the names of the networks, up to a maximum
365 Call {!num_of_networks} first to get a value for [max].
367 val num_of_defined_networks : [>`R] t -> int
368 (** Returns the number of inactive networks. *)
369 val list_defined_networks : [>`R] t -> int -> string array
370 (** [list_defined_networks conn max]
371 returns the names of the inactive networks, up to a maximum
373 Call {!num_of_defined_networks} first to get a value for [max].
376 val num_of_pools : [>`R] t -> int
377 (** Returns the number of storage pools. *)
378 val list_pools : [>`R] t -> int -> string array
379 (** Return list of storage pools. *)
380 val num_of_defined_pools : [>`R] t -> int
381 (** Returns the number of storage pools. *)
382 val list_defined_pools : [>`R] t -> int -> string array
383 (** Return list of storage pools. *)
385 (* The name of this function is inconsistent, but the inconsistency
386 * is really in libvirt itself.
388 val num_of_secrets : [>`R] t -> int
389 (** Returns the number of secrets. *)
390 val list_secrets : [>`R] t -> int -> string array
391 (** Returns the list of secrets. *)
392 val get_node_info : [>`R] t -> node_info
393 (** Return information about the physical server. *)
395 val node_get_free_memory : [> `R] t -> int64
397 [node_get_free_memory conn]
398 returns the amount of free memory (not allocated to any guest)
402 val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array
404 [node_get_cells_free_memory conn start max]
405 returns the amount of free memory on each NUMA cell in kilobytes.
406 [start] is the first cell for which we return free memory.
407 [max] is the maximum number of cells for which we return free memory.
408 Returns an array of up to [max] entries in length.
411 val maxcpus_of_node_info : node_info -> int
412 (** Calculate the total number of CPUs supported (but not necessarily
416 val cpumaplen : int -> int
417 (** Calculate the length (in bytes) required to store the complete
418 CPU map between a single virtual and all physical CPUs of a domain.
421 val use_cpu : bytes -> int -> unit
422 (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
423 val unuse_cpu : bytes -> int -> unit
424 (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
425 val cpu_usable : bytes -> int -> int -> int -> bool
426 (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
427 [cpu] is usable by [vcpu]. *)
429 val set_keep_alive : [>`R] t -> int -> int -> unit
430 (** [set_keep_alive conn interval count] starts sending keepalive
431 messages after [interval] seconds of inactivity and consider the
432 connection to be broken when no response is received after [count]
434 Note: the client has to implement and run an event loop to
435 be able to use keep-alive messages. *)
437 val get_auth_default : unit -> auth
438 (** [get_auth_default ()] returns the default authentication handler
442 external const : [>`R] t -> ro t = "%identity"
443 (** [const conn] turns a read/write connection into a read-only
444 connection. Note that the opposite operation is impossible.
447 (** Module dealing with connections. [Connect.t] is the
448 connection object. *)
455 (** Domain handle. Read-only handles have type [ro Domain.t] and
456 read-write handles have type [rw Domain.t].
460 | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
461 | InfoShutdown | InfoShutoff | InfoCrashed
464 state : state; (** running state *)
465 max_mem : int64; (** maximum memory in kilobytes *)
466 memory : int64; (** memory used in kilobytes *)
467 nr_virt_cpu : int; (** number of virtual CPUs *)
468 cpu_time : int64; (** CPU time used in nanoseconds *)
471 type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
474 number : int; (** virtual CPU number *)
475 vcpu_state : vcpu_state; (** state *)
476 vcpu_time : int64; (** CPU time used in nanoseconds *)
477 cpu : int; (** real CPU number, -1 if offline *)
480 type domain_create_flag =
481 | START_PAUSED (** Launch guest in paused state *)
482 | START_AUTODESTROY (** Automatically kill guest on close *)
483 | START_BYPASS_CACHE (** Avoid filesystem cache pollution *)
484 | START_FORCE_BOOT (** Discard any managed save *)
485 | START_VALIDATE (** Validate XML against schema *)
487 type sched_param = string * sched_param_value
488 and sched_param_value =
489 | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
490 | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
491 | SchedFieldFloat of float | SchedFieldBool of bool
493 type typed_param = string * typed_param_value
494 and typed_param_value =
495 | TypedFieldInt32 of int32 | TypedFieldUInt32 of int32
496 | TypedFieldInt64 of int64 | TypedFieldUInt64 of int64
497 | TypedFieldFloat of float | TypedFieldBool of bool
498 | TypedFieldString of string
500 type migrate_flag = Live
502 type memory_flag = Virtual
517 type interface_stats = {
528 type get_all_domain_stats_flag =
529 | GetAllDomainsStatsActive
530 | GetAllDomainsStatsInactive
531 | GetAllDomainsStatsOther
532 | GetAllDomainsStatsPaused
533 | GetAllDomainsStatsPersistent
534 | GetAllDomainsStatsRunning
535 | GetAllDomainsStatsShutoff
536 | GetAllDomainsStatsTransient
537 | GetAllDomainsStatsBacking
538 | GetAllDomainsStatsEnforceStats
541 | StatsState | StatsCpuTotal | StatsBalloon | StatsVcpu
542 | StatsInterface | StatsBlock | StatsPerf
544 type domain_stats_record = {
546 params : typed_param array;
550 | XmlSecure (* dump security sensitive information too *)
551 | XmlInactive (* dump inactive domain information *)
552 | XmlUpdateCPU (* update guest CPU requirements according to host CPU *)
553 | XmlMigratable (* dump XML suitable for migration *)
555 val max_peek : [>`R] t -> int
556 (** Maximum size supported by the {!block_peek} and {!memory_peek}
557 functions. If you want to peek more than this then you must
558 break your request into chunks. *)
560 val create_linux : [>`W] Connect.t -> xml -> rw t
561 (** Create a new guest domain (not necessarily a Linux one)
562 from the given XML. Use {!create_xml} instead.
564 val create_xml : [>`W] Connect.t -> xml -> domain_create_flag list -> rw t
565 (** Create a new guest domain from the given XML. *)
566 val lookup_by_id : 'a Connect.t -> int -> 'a t
567 (** Lookup a domain by ID. *)
568 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
569 (** Lookup a domain by UUID. This uses the packed byte array UUID. *)
570 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
571 (** Lookup a domain by (string) UUID. *)
572 val lookup_by_name : 'a Connect.t -> string -> 'a t
573 (** Lookup a domain by name. *)
574 val destroy : [>`W] t -> unit
575 (** Abruptly destroy a domain. *)
576 val free : [>`R] t -> unit
577 (** [free domain] frees the domain object in memory.
579 The domain object is automatically freed if it is garbage
580 collected. This function just forces it to be freed right
584 val suspend : [>`W] t -> unit
585 (** Suspend a domain. *)
586 val resume : [>`W] t -> unit
587 (** Resume a domain. *)
588 val save : [>`W] t -> filename -> unit
589 (** Suspend a domain, then save it to the file. *)
590 val restore : [>`W] Connect.t -> filename -> unit
591 (** Restore a domain from a file. *)
592 val core_dump : [>`W] t -> filename -> unit
593 (** Force a domain to core dump to the named file. *)
594 val shutdown : [>`W] t -> unit
595 (** Shutdown a domain. *)
596 val reboot : [>`W] t -> unit
597 (** Reboot a domain. *)
598 val get_name : [>`R] t -> string
599 (** Get the domain name. *)
600 val get_uuid : [>`R] t -> uuid
601 (** Get the domain UUID (as a packed byte array). *)
602 val get_uuid_string : [>`R] t -> string
603 (** Get the domain UUID (as a printable string). *)
604 val get_id : [>`R] t -> int
605 (** [get_id dom] returns the ID of the domain. In most cases
606 this returns [-1] if the domain is not running. *)
607 val get_os_type : [>`R] t -> string
608 (** Get the operating system type. *)
609 val get_max_memory : [>`R] t -> int64
610 (** Get the maximum memory allocation. *)
611 val set_max_memory : [>`W] t -> int64 -> unit
612 (** Set the maximum memory allocation. *)
613 val set_memory : [>`W] t -> int64 -> unit
614 (** Set the normal memory allocation. *)
615 val get_info : [>`R] t -> info
616 (** Get information about a domain. *)
617 val get_xml_desc : [>`R] t -> xml
618 (** Get the XML description of a domain. *)
619 val get_xml_desc_flags : [>`W] t -> xml_desc_flag list -> xml
620 (** Get the XML description of a domain, with the possibility
622 val get_scheduler_type : [>`R] t -> string * int
623 (** Get the scheduler type. *)
624 val get_scheduler_parameters : [>`R] t -> int -> sched_param array
625 (** Get the array of scheduler parameters. *)
626 val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
627 (** Set the array of scheduler parameters. *)
628 val define_xml : [>`W] Connect.t -> xml -> rw t
629 (** Define a new domain (but don't start it up) from the XML. *)
630 val undefine : [>`W] t -> unit
631 (** Undefine a domain - removes its configuration. *)
632 val create : [>`W] t -> unit
633 (** Launch a defined (inactive) domain. *)
634 val get_autostart : [>`R] t -> bool
635 (** Get the autostart flag for a domain. *)
636 val set_autostart : [>`W] t -> bool -> unit
637 (** Set the autostart flag for a domain. *)
638 val set_vcpus : [>`W] t -> int -> unit
639 (** Change the number of vCPUs available to a domain. *)
640 val pin_vcpu : [>`W] t -> int -> string -> unit
641 (** [pin_vcpu dom vcpu bitmap] pins a domain vCPU to a bitmap of physical
642 CPUs. See the libvirt documentation for details of the
643 layout of the bitmap. *)
644 val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
645 (** [get_vcpus dom maxinfo maplen] returns the pinning information
646 for a domain. See the libvirt documentation for details
647 of the array and bitmap returned from this function.
649 val get_cpu_stats : [>`R] t -> typed_param list array
650 (** [get_pcpu_stats dom] returns the physical CPU stats
651 for a domain. See the libvirt documentation for details.
653 val get_max_vcpus : [>`R] t -> int
654 (** Returns the maximum number of vCPUs supported for this domain. *)
655 val attach_device : [>`W] t -> xml -> unit
656 (** Attach a device (described by the device XML) to a domain. *)
657 val detach_device : [>`W] t -> xml -> unit
658 (** Detach a device (described by the device XML) from a domain. *)
660 val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
661 ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
662 (** [migrate dom dconn flags ()] migrates a domain to a
663 destination host described by [dconn].
665 The optional flag [?dname] is used to rename the domain.
667 The optional flag [?uri] is used to route the migration.
669 The optional flag [?bandwidth] is used to limit the bandwidth
670 used for migration (in Mbps). *)
672 val block_stats : [>`R] t -> string -> block_stats
673 (** Returns block device stats. *)
674 val interface_stats : [>`R] t -> string -> interface_stats
675 (** Returns network interface stats. *)
677 val block_peek : [>`W] t -> string -> int64 -> int -> string -> int -> unit
678 (** [block_peek dom path offset size buf boff] reads [size] bytes at
679 [offset] in the domain's [path] block device.
681 If successful then the data is written into [buf] starting
682 at offset [boff], for [size] bytes.
684 See also {!max_peek}. *)
685 val memory_peek : [>`W] t -> memory_flag list -> int64 -> int ->
686 string -> int -> unit
687 (** [memory_peek dom Virtual offset size] reads [size] bytes
688 at [offset] in the domain's virtual memory.
690 If successful then the data is written into [buf] starting
691 at offset [boff], for [size] bytes.
693 See also {!max_peek}. *)
695 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"
696 (** [get_all_domain_stats conn stats flags] allows you to read
697 all stats across multiple/all domains in a single call.
699 See the libvirt documentation for
700 [virConnectGetAllDomainStats]. *)
702 external const : [>`R] t -> ro t = "%identity"
703 (** [const dom] turns a read/write domain handle into a read-only
704 domain handle. Note that the opposite operation is impossible.
707 val get_domains : ([>`R] as 'a) Connect.t -> list_flag list -> 'a t list
708 (** Get the active and/or inactive domains using the most
709 efficient method available.
712 {!get_domains_and_infos},
713 {!Connect.list_domains},
714 {!Connect.list_defined_domains}.
717 val get_domains_and_infos : ([>`R] as 'a) Connect.t -> list_flag list ->
719 (** This gets the active and/or inactive domains and the
720 domain info for each one using the most efficient
725 {!Connect.list_domains},
726 {!Connect.list_defined_domains},
731 (** Module dealing with domains. [Domain.t] is the
739 | `Added (** Newly created config file *)
740 | `Updated (** Changed config file *)
744 val to_string: t -> string
747 module Undefined : sig
749 | `Removed (** Deleted the config file *)
753 val to_string: t -> string
758 | `Booted (** Normal startup from boot *)
759 | `Migrated (** Incoming migration from another host *)
760 | `Restored (** Restored from a state file *)
761 | `FromSnapshot (** Restored from snapshot *)
762 | `Wakeup (** Started due to wakeup event *)
766 val to_string: t -> string
769 module Suspended : sig
771 | `Paused (** Normal suspend due to admin pause *)
772 | `Migrated (** Suspended for offline migration *)
773 | `IOError (** Suspended due to a disk I/O error *)
774 | `Watchdog (** Suspended due to a watchdog firing *)
775 | `Restored (** Restored from paused state file *)
776 | `FromSnapshot (** Restored from paused snapshot *)
777 | `APIError (** suspended after failure during libvirt API call *)
781 val to_string: t -> string
786 | `Unpaused (** Normal resume due to admin unpause *)
787 | `Migrated (** Resumed for completion of migration *)
788 | `FromSnapshot (** Resumed from snapshot *)
792 val to_string: t -> string
797 | `Shutdown (** Normal shutdown *)
798 | `Destroyed (** Forced poweroff from host *)
799 | `Crashed (** Guest crashed *)
800 | `Migrated (** Migrated off to another host *)
801 | `Saved (** Saved to a state file *)
802 | `Failed (** Host emulator/mgmt failed *)
803 | `FromSnapshot (** offline snapshot loaded *)
807 val to_string: t -> string
810 module PM_suspended : sig
812 | `Memory (** Guest was PM suspended to memory *)
813 | `Disk (** Guest was PM suspended to disk *)
817 val to_string: t -> string
820 module Lifecycle : sig
822 | `Defined of Defined.t
823 | `Undefined of Undefined.t
824 | `Started of Started.t
825 | `Suspended of Suspended.t
826 | `Resumed of Resumed.t
827 | `Stopped of Stopped.t
828 | `Shutdown (* no detail defined yet *)
829 | `PMSuspended of PM_suspended.t
833 val to_string: t -> string
839 val to_string: t -> string
842 module Rtc_change : sig
845 val to_string: t -> string
848 module Watchdog : sig
850 | `None (** No action, watchdog ignored *)
851 | `Pause (** Guest CPUs are paused *)
852 | `Reset (** Guest CPUs are reset *)
853 | `Poweroff (** Guest is forcably powered off *)
854 | `Shutdown (** Guest is requested to gracefully shutdown *)
855 | `Debug (** No action, a debug message logged *)
856 | `Unknown of int (** newer libvirt *)
859 val to_string: t -> string
862 module Io_error : sig
863 (** Represents both IOError and IOErrorReason *)
865 | `None (** No action, IO error ignored *)
866 | `Pause (** Guest CPUs are paused *)
867 | `Report (** IO error reported to guest OS *)
868 | `Unknown of int (** newer libvirt *)
872 src_path: string option; (** The host file on which the I/O error occurred *)
873 dev_alias: string option; (** The guest device alias associated with the path *)
874 action: action; (** The action that is to be taken due to the IO error *)
875 reason: string option; (** The cause of the IO error *)
878 val to_string: t -> string
881 module Graphics_address : sig
883 | `Ipv4 (** IPv4 address *)
884 | `Ipv6 (** IPv6 address *)
885 | `Unix (** UNIX socket path *)
886 | `Unknown of int (** newer libvirt *)
890 family: family; (** Address family *)
891 node: string option; (** Address of node (eg IP address, or UNIX path *)
892 service: string option; (** Service name/number (eg TCP port, or NULL) *)
895 val to_string: t -> string
898 module Graphics_subject : sig
900 ty: string option; (** Type of identity *)
901 name: string option; (** Identity value *)
904 type t = identity list
906 val to_string: t -> string
909 module Graphics : sig
911 | `Connect (** Initial socket connection established *)
912 | `Initialize (** Authentication & setup completed *)
913 | `Disconnect (** Final socket disconnection *)
914 | `Unknown of int (** newer libvirt *)
918 phase: phase; (** the phase of the connection *)
919 local: Graphics_address.t; (** the local server address *)
920 remote: Graphics_address.t; (** the remote client address *)
921 auth_scheme: string option; (** the authentication scheme activated *)
922 subject: Graphics_subject.t; (** the authenticated subject (user) *)
925 val to_string: t -> string
928 module Control_error : sig
931 val to_string: t -> string
934 module Block_job : sig
936 | `KnownUnknown (** explicitly named UNKNOWN in the spec *)
952 disk: string option; (** fully-qualified name of the affected disk *)
953 ty: ty; (** type of block job *)
954 status: status; (** final status of the operation *)
957 val to_string: t -> string
960 module Disk_change : sig
967 old_src_path: string option; (** old source path *)
968 new_src_path: string option; (** new source path *)
969 dev_alias: string option; (** device alias name *)
970 reason: reason; (** reason why this callback was called *)
973 val to_string: t -> string
976 module Tray_change : sig
984 dev_alias: string option; (** device alias *)
985 reason: reason; (** why the tray status was changed *)
988 val to_string: t -> string
991 module PM_wakeup : sig
998 val to_string: t -> string
1001 module PM_suspend : sig
1008 val to_string: t -> string
1011 module Balloon_change : sig
1014 val to_string: t -> string
1017 module PM_suspend_disk : sig
1024 val to_string: t -> string
1029 | Lifecycle of ([`R] Domain.t -> Lifecycle.t -> unit)
1030 | Reboot of ([`R] Domain.t -> Reboot.t -> unit)
1031 | RtcChange of ([`R] Domain.t -> Rtc_change.t -> unit)
1032 | Watchdog of ([`R] Domain.t -> Watchdog.t -> unit)
1033 | IOError of ([`R] Domain.t -> Io_error.t -> unit)
1034 | Graphics of ([`R] Domain.t -> Graphics.t -> unit)
1035 | IOErrorReason of ([`R] Domain.t -> Io_error.t -> unit)
1036 | ControlError of ([`R] Domain.t -> Control_error.t -> unit)
1037 | BlockJob of ([`R] Domain.t -> Block_job.t -> unit)
1038 | DiskChange of ([`R] Domain.t -> Disk_change.t -> unit)
1039 | TrayChange of ([`R] Domain.t -> Tray_change.t -> unit)
1040 | PMWakeUp of ([`R] Domain.t -> PM_wakeup.t -> unit)
1041 | PMSuspend of ([`R] Domain.t -> PM_suspend.t -> unit)
1042 | BalloonChange of ([`R] Domain.t -> Balloon_change.t -> unit)
1043 | PMSuspendDisk of ([`R] Domain.t -> PM_suspend_disk.t -> unit)
1045 (** type of a registered call back function *)
1047 val register_default_impl : unit -> unit
1048 (** Registers the default event loop based on poll(). This
1049 must be done before connections are opened.
1051 Once registered call run_default_impl in a loop. *)
1053 val run_default_impl : unit -> unit
1054 (** Runs one iteration of the event loop. Applications will
1055 generally want to have a thread which invokes this in an
1059 (** an individual event registration *)
1061 val register_any : 'a Connect.t -> ?dom:'a Domain.t -> callback -> callback_id
1062 (** [register_any con ?dom callback] registers [callback]
1063 to receive notification of arbitrary domain events. Return
1064 a registration id which can be used in [deregister_any].
1066 If [?dom] is None then register for this kind of event on
1067 all domains. If [dom] is [Some d] then register for this
1068 kind of event only on [d].
1071 val deregister_any : 'a Connect.t -> callback_id -> unit
1072 (** [deregister_any con id] deregisters the previously registered
1073 callback with id [id]. *)
1076 (** an individual timer event *)
1078 val add_timeout : 'a Connect.t -> int -> (unit -> unit) -> timer_id
1079 (** [add_timeout con ms cb] registers [cb] as a timeout callback
1080 which will be called every [ms] milliseconds *)
1082 val remove_timeout : 'a Connect.t -> timer_id -> unit
1083 (** [remove_timeout con t] deregisters timeout callback [t]. *)
1086 (** Module dealing with events generated by domain
1094 (** Network handle. Read-only handles have type [ro Network.t] and
1095 read-write handles have type [rw Network.t].
1098 val lookup_by_name : 'a Connect.t -> string -> 'a t
1099 (** Lookup a network by name. *)
1100 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
1101 (** Lookup a network by (packed) UUID. *)
1102 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
1103 (** Lookup a network by UUID string. *)
1104 val create_xml : [>`W] Connect.t -> xml -> rw t
1105 (** Create a network. *)
1106 val define_xml : [>`W] Connect.t -> xml -> rw t
1107 (** Define but don't activate a network. *)
1108 val undefine : [>`W] t -> unit
1109 (** Undefine configuration of a network. *)
1110 val create : [>`W] t -> unit
1111 (** Start up a defined (inactive) network. *)
1112 val destroy : [>`W] t -> unit
1113 (** Destroy a network. *)
1114 val free : [>`R] t -> unit
1115 (** [free network] frees the network object in memory.
1117 The network object is automatically freed if it is garbage
1118 collected. This function just forces it to be freed right
1122 val get_name : [>`R] t -> string
1123 (** Get network name. *)
1124 val get_uuid : [>`R] t -> uuid
1125 (** Get network packed UUID. *)
1126 val get_uuid_string : [>`R] t -> string
1127 (** Get network UUID as a printable string. *)
1128 val get_xml_desc : [>`R] t -> xml
1129 (** Get XML description of a network. *)
1130 val get_bridge_name : [>`R] t -> string
1131 (** Get bridge device name of a network. *)
1132 val get_autostart : [>`R] t -> bool
1133 (** Get the autostart flag for a network. *)
1134 val set_autostart : [>`W] t -> bool -> unit
1135 (** Set the autostart flag for a network. *)
1137 external const : [>`R] t -> ro t = "%identity"
1138 (** [const network] turns a read/write network handle into a read-only
1139 network handle. Note that the opposite operation is impossible.
1142 (** Module dealing with networks. [Network.t] is the
1145 (** {3 Storage pools} *)
1150 (** Storage pool handle. *)
1152 type pool_state = Inactive | Building | Running | Degraded
1153 (** State of the storage pool. *)
1155 type pool_build_flags = New | Repair | Resize
1156 (** Flags for creating a storage pool. *)
1158 type pool_delete_flags = Normal | Zeroed
1159 (** Flags for deleting a storage pool. *)
1162 state : pool_state; (** Pool state. *)
1163 capacity : int64; (** Logical size in bytes. *)
1164 allocation : int64; (** Currently allocated in bytes. *)
1165 available : int64; (** Remaining free space bytes. *)
1168 val lookup_by_name : 'a Connect.t -> string -> 'a t
1169 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
1170 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
1171 (** Look up a storage pool by name, UUID or UUID string. *)
1173 val create_xml : [>`W] Connect.t -> xml -> rw t
1174 (** Create a storage pool. *)
1175 val define_xml : [>`W] Connect.t -> xml -> rw t
1176 (** Define but don't activate a storage pool. *)
1177 val build : [>`W] t -> pool_build_flags -> unit
1178 (** Build a storage pool. *)
1179 val undefine : [>`W] t -> unit
1180 (** Undefine configuration of a storage pool. *)
1181 val create : [>`W] t -> unit
1182 (** Start up a defined (inactive) storage pool. *)
1183 val destroy : [>`W] t -> unit
1184 (** Destroy a storage pool. *)
1185 val delete : [>`W] t -> unit
1186 (** Delete a storage pool. *)
1187 val free : [>`R] t -> unit
1188 (** Free a storage pool object in memory.
1190 The storage pool object is automatically freed if it is garbage
1191 collected. This function just forces it to be freed right
1194 val refresh : [`R] t -> unit
1195 (** Refresh the list of volumes in the storage pool. *)
1197 val get_name : [`R] t -> string
1198 (** Name of the pool. *)
1199 val get_uuid : [`R] t -> uuid
1200 (** Get the UUID (as a packed byte array). *)
1201 val get_uuid_string : [`R] t -> string
1202 (** Get the UUID (as a printable string). *)
1203 val get_info : [`R] t -> pool_info
1204 (** Get information about the pool. *)
1205 val get_xml_desc : [`R] t -> xml
1206 (** Get the XML description. *)
1207 val get_autostart : [`R] t -> bool
1208 (** Get the autostart flag for the storage pool. *)
1209 val set_autostart : [>`W] t -> bool -> unit
1210 (** Set the autostart flag for the storage pool. *)
1212 val num_of_volumes : [`R] t -> int
1213 (** Returns the number of storage volumes within the storage pool. *)
1214 val list_volumes : [`R] t -> int -> string array
1215 (** Return list of storage volumes. *)
1217 external const : [>`R] t -> ro t = "%identity"
1218 (** [const conn] turns a read/write storage pool into a read-only
1219 pool. Note that the opposite operation is impossible.
1222 (** Module dealing with storage pools. *)
1224 (** {3 Storage volumes} *)
1229 (** Storage volume handle. *)
1231 type vol_type = File | Block
1232 (** Type of a storage volume. *)
1234 type vol_delete_flags = Normal | Zeroed
1235 (** Flags for deleting a storage volume. *)
1238 typ : vol_type; (** Type of storage volume. *)
1239 capacity : int64; (** Logical size in bytes. *)
1240 allocation : int64; (** Currently allocated in bytes. *)
1243 val lookup_by_name : 'a Pool.t -> string -> 'a t
1244 val lookup_by_key : 'a Connect.t -> string -> 'a t
1245 val lookup_by_path : 'a Connect.t -> string -> 'a t
1246 (** Look up a storage volume by name, key or path volume. *)
1248 val pool_of_volume : 'a t -> 'a Pool.t
1249 (** Get the storage pool containing this volume. *)
1251 val get_name : [`R] t -> string
1252 (** Name of the volume. *)
1253 val get_key : [`R] t -> string
1254 (** Key of the volume. *)
1255 val get_path : [`R] t -> string
1256 (** Path of the volume. *)
1257 val get_info : [`R] t -> vol_info
1258 (** Get information about the storage volume. *)
1259 val get_xml_desc : [`R] t -> xml
1260 (** Get the XML description. *)
1262 val create_xml : [>`W] Pool.t -> xml -> unit
1263 (** Create a storage volume. *)
1264 val delete : [>`W] t -> vol_delete_flags -> unit
1265 (** Delete a storage volume. *)
1266 val free : [>`R] t -> unit
1267 (** Free a storage volume object in memory.
1269 The storage volume object is automatically freed if it is garbage
1270 collected. This function just forces it to be freed right
1274 external const : [>`R] t -> ro t = "%identity"
1275 (** [const conn] turns a read/write storage volume into a read-only
1276 volume. Note that the opposite operation is impossible.
1279 (** Module dealing with storage volumes. *)
1286 (** Secret handle. *)
1288 type secret_usage_type =
1294 (** Usage type of a secret. *)
1296 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
1297 (** Lookup a secret by UUID. This uses the packed byte array UUID. *)
1298 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
1299 (** Lookup a secret by (string) UUID. *)
1300 val lookup_by_usage : 'a Connect.t -> secret_usage_type -> string -> 'a t
1301 (** Lookup a secret by usage type, and usage ID. *)
1303 val define_xml : [>`W] Connect.t -> xml -> rw t
1304 (** Define a secret. *)
1306 val get_uuid : [>`R] t -> uuid
1307 (** Get the UUID (as a packed byte array) of the secret. *)
1308 val get_uuid_string : [>`R] t -> string
1309 (** Get the UUID (as a printable string) of the secret. *)
1310 val get_usage_type : [>`R] t -> secret_usage_type
1311 (** Get the usage type of the secret. *)
1312 val get_usage_id : [>`R] t -> string
1313 (** Get the usage ID of the secret. *)
1314 val get_xml_desc : [>`R] t -> xml
1315 (** Get the XML description. *)
1317 val set_value : [>`W] t -> bytes -> unit
1318 (** Set a new value for the secret. *)
1319 val get_value : [>`R] t -> bytes
1320 (** Get the value of the secret. *)
1322 val undefine : [>`W] t -> unit
1323 (** Undefine a secret. *)
1325 val free : [>`R] t -> unit
1326 (** Free a secret object in memory.
1328 The secret object is automatically freed if it is garbage
1329 collected. This function just forces it to be freed right
1333 external const : [>`R] t -> ro t = "%identity"
1334 (** [const conn] turns a read/write secret into a read-only
1335 secret. Note that the opposite operation is impossible.
1338 (** Module dealing with secrets. *)
1340 (** {3 Error handling and exceptions} *)
1346 | VIR_ERR_INTERNAL_ERROR
1348 | VIR_ERR_NO_SUPPORT
1349 | VIR_ERR_UNKNOWN_HOST
1350 | VIR_ERR_NO_CONNECT
1351 | VIR_ERR_INVALID_CONN
1352 | VIR_ERR_INVALID_DOMAIN
1353 | VIR_ERR_INVALID_ARG
1354 | VIR_ERR_OPERATION_FAILED
1355 | VIR_ERR_GET_FAILED
1356 | VIR_ERR_POST_FAILED
1357 | VIR_ERR_HTTP_ERROR
1358 | VIR_ERR_SEXPR_SERIAL
1369 | VIR_ERR_NO_XENSTORE
1370 | VIR_ERR_DRIVER_FULL
1371 | VIR_ERR_CALL_FAILED
1374 | VIR_ERR_OPERATION_DENIED
1375 | VIR_ERR_OPEN_FAILED
1376 | VIR_ERR_READ_FAILED
1377 | VIR_ERR_PARSE_FAILED
1378 | VIR_ERR_CONF_SYNTAX
1379 | VIR_ERR_WRITE_FAILED
1380 | VIR_ERR_XML_DETAIL
1381 | VIR_ERR_INVALID_NETWORK
1382 | VIR_ERR_NETWORK_EXIST
1383 | VIR_ERR_SYSTEM_ERROR
1385 | VIR_ERR_GNUTLS_ERROR
1386 | VIR_WAR_NO_NETWORK
1388 | VIR_ERR_NO_NETWORK
1389 | VIR_ERR_INVALID_MAC
1390 | VIR_ERR_AUTH_FAILED
1391 | VIR_ERR_INVALID_STORAGE_POOL
1392 | VIR_ERR_INVALID_STORAGE_VOL
1393 | VIR_WAR_NO_STORAGE
1394 | VIR_ERR_NO_STORAGE_POOL
1395 | VIR_ERR_NO_STORAGE_VOL
1397 | VIR_ERR_INVALID_NODE_DEVICE
1398 | VIR_ERR_NO_NODE_DEVICE
1399 | VIR_ERR_NO_SECURITY_MODEL
1400 | VIR_ERR_OPERATION_INVALID
1401 | VIR_WAR_NO_INTERFACE
1402 | VIR_ERR_NO_INTERFACE
1403 | VIR_ERR_INVALID_INTERFACE
1404 | VIR_ERR_MULTIPLE_INTERFACES
1405 | VIR_WAR_NO_NWFILTER
1406 | VIR_ERR_INVALID_NWFILTER
1407 | VIR_ERR_NO_NWFILTER
1408 | VIR_ERR_BUILD_FIREWALL
1410 | VIR_ERR_INVALID_SECRET
1412 | VIR_ERR_CONFIG_UNSUPPORTED
1413 | VIR_ERR_OPERATION_TIMEOUT
1414 | VIR_ERR_MIGRATE_PERSIST_FAILED
1415 | VIR_ERR_HOOK_SCRIPT_FAILED
1416 | VIR_ERR_INVALID_DOMAIN_SNAPSHOT
1417 | VIR_ERR_NO_DOMAIN_SNAPSHOT
1418 | VIR_ERR_INVALID_STREAM
1419 | VIR_ERR_ARGUMENT_UNSUPPORTED
1420 | VIR_ERR_STORAGE_PROBE_FAILED
1421 | VIR_ERR_STORAGE_POOL_BUILT
1422 | VIR_ERR_SNAPSHOT_REVERT_RISKY
1423 | VIR_ERR_OPERATION_ABORTED
1424 | VIR_ERR_AUTH_CANCELLED
1425 | VIR_ERR_NO_DOMAIN_METADATA
1426 | VIR_ERR_MIGRATE_UNSAFE
1428 | VIR_ERR_BLOCK_COPY_ACTIVE
1429 | VIR_ERR_OPERATION_UNSUPPORTED
1431 | VIR_ERR_AGENT_UNRESPONSIVE
1432 | VIR_ERR_RESOURCE_BUSY
1433 | VIR_ERR_ACCESS_DENIED
1434 | VIR_ERR_DBUS_SERVICE
1435 | VIR_ERR_STORAGE_VOL_EXIST
1436 | VIR_ERR_CPU_INCOMPATIBLE
1437 | VIR_ERR_XML_INVALID_SCHEMA
1438 | VIR_ERR_MIGRATE_FINISH_OK
1439 | VIR_ERR_AUTH_UNAVAILABLE
1442 | VIR_ERR_AGENT_UNSYNCED
1444 | VIR_ERR_DEVICE_MISSING
1445 | VIR_ERR_INVALID_NWFILTER_BINDING
1446 | VIR_ERR_NO_NWFILTER_BINDING
1447 (* ^^ NB: If you add a variant you MUST edit
1448 libvirt_c_epilogue.c:MAX_VIR_* *)
1449 | VIR_ERR_UNKNOWN of int
1450 (** See [<libvirt/virterror.h>] for meaning of these codes. *)
1452 val string_of_code : code -> string
1471 | VIR_FROM_STATS_LINUX
1478 | VIR_FROM_XEN_INOTIFY
1481 | VIR_FROM_INTERFACE
1490 | VIR_FROM_DOMAIN_SNAPSHOT
1499 | VIR_FROM_CAPABILITIES
1503 | VIR_FROM_PARALLELS
1506 | VIR_FROM_LOCKSPACE
1523 (* ^^ NB: If you add a variant you MUST edit
1524 libvirt_c_epilogue.c: MAX_VIR_* *)
1525 | VIR_FROM_UNKNOWN of int
1526 (** Subsystem / driver which produced the error. *)
1528 val string_of_domain : domain -> string
1534 (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *)
1535 | VIR_ERR_UNKNOWN_LEVEL of int
1536 (** No error, a warning or an error. *)
1538 val string_of_level : level -> string
1541 code : code; (** Error code. *)
1542 domain : domain; (** Origin of the error. *)
1543 message : string option; (** Human-readable message. *)
1544 level : level; (** Error or warning. *)
1545 str1 : string option; (** Informational string. *)
1546 str2 : string option; (** Informational string. *)
1547 str3 : string option; (** Informational string. *)
1548 int1 : int32; (** Informational integer. *)
1549 int2 : int32; (** Informational integer. *)
1551 (** An error object. *)
1553 val to_string : t -> string
1554 (** Turn the exception into a printable string. *)
1556 val get_last_error : unit -> t option
1557 val get_last_conn_error : [>`R] Connect.t -> t option
1558 (** Get the last error at a global or connection level.
1560 Normally you do not need to use these functions because
1561 the library automatically turns errors into exceptions.
1564 val reset_last_error : unit -> unit
1565 val reset_last_conn_error : [>`R] Connect.t -> unit
1566 (** Reset the error at a global or connection level.
1568 Normally you do not need to use these functions.
1571 val no_error : unit -> t
1572 (** Creates an empty error message.
1574 Normally you do not need to use this function.
1577 (** Module dealing with errors. *)
1579 exception Virterror of Virterror.t
1580 (** This exception can be raised by any library function that detects
1581 an error. To get a printable error message, call
1582 {!Virterror.to_string} on the content of this exception.
1585 exception Not_supported of string
1588 [Not_supported "virFoo"]
1589 (where [virFoo] is the libvirt function name) if a function is
1590 not supported at either compile or run time. This applies to
1591 any libvirt function added after version 0.2.1.
1593 See also {{:https://libvirt.org/hvsupport.html}https://libvirt.org/hvsupport.html}
1596 (** {3 Utility functions} *)
1598 val map_ignore_errors : ('a -> 'b) -> 'a list -> 'b list
1599 (** [map_ignore_errors f xs] calls function [f] for each element of [xs].
1601 This is just like [List.map] except that if [f x] throws a
1602 {!Virterror.t} exception, the error is ignored and [f x]
1603 is not returned in the final list.
1605 This function is primarily useful when dealing with domains which
1606 might 'disappear' asynchronously from the currently running