1 (** OCaml bindings for libvirt.
2 (C) Copyright 2007 Richard W.M. Jones, Red Hat Inc.
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Lesser General Public License for more details.
15 You should have received a copy of the GNU Lesser General Public
16 License along with this library; if not, write to the Free Software
17 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
21 (** This is a "raw" UUID, ie. a packed string of bytes. *)
24 (** Type of XML (an uninterpreted string of bytes). Use PXP, expat,
25 xml-light, etc. if you want to do anything useful with the XML.
28 val get_version : ?driver:string -> unit -> int * int
29 (** [get_version ()] returns the library version in the first part
30 of the tuple, and [0] in the second part.
32 [get_version ~driver ()] returns the library version in the first
33 part of the tuple, and the version of the driver called [driver]
36 The version numbers are encoded as
37 1,000,000 * major + 1,000 * minor + release.
41 (** Length of packed UUIDs. *)
43 val uuid_string_length : int
44 (** Length of UUID strings. *)
46 (* These phantom types are used to ensure the type-safety of read-only
47 * versus read-write connections. For more information see:
48 * http://caml.inria.fr/pub/ml-archives/caml-list/2004/07/80683af867cce6bf8fff273973f70c95.en.html
56 (** Connection. Read-only connections have type [ro Connect.t] and
57 read-write connections have type [rw Connect.t].
61 model : string; (** CPU model *)
62 memory : int64; (** memory size in kilobytes *)
63 cpus : int; (** number of active CPUs *)
64 mhz : int; (** expected CPU frequency *)
65 nodes : int; (** number of NUMA nodes (1 = UMA) *)
66 sockets : int; (** number of CPU sockets per node *)
67 cores : int; (** number of cores per socket *)
68 threads : int; (** number of threads per core *)
71 val connect : ?name:string -> unit -> rw t
72 val connect_readonly : ?name:string -> unit -> ro t
73 (** [connect ~name ()] connects to the hypervisor with URI [name].
75 [connect ()] connects to the default hypervisor.
77 [connect_readonly] is the same but connects in read-only mode.
80 val close : [>`R] t -> unit
81 (** [close conn] closes and frees the connection object in memory.
83 The connection is automatically closed if it is garbage
84 collected. This function just forces it to be closed
88 val get_type : [>`R] t -> string
89 val get_version : [>`R] t -> int
90 val get_hostname : [>`R] t -> string
91 val get_uri : [>`R] t -> string
92 val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
93 val list_domains : [>`R] t -> int -> int array
94 val num_of_domains : [>`R] t -> int
95 val get_capabilities : [>`R] t -> string
96 val num_of_defined_domains : [>`R] t -> int
97 val list_defined_domains : [>`R] t -> int -> string array
98 val num_of_networks : [>`R] t -> int
99 val list_networks : [>`R] t -> int -> string array
100 val num_of_defined_networks : [>`R] t -> int
101 val list_defined_networks : [>`R] t -> int -> string array
103 (* The name of this function is inconsistent, but the inconsistency
104 * is really in libvirt itself.
106 val get_node_info : [>`R] t -> node_info
108 val maxcpus_of_node_info : node_info -> int
109 (** Calculate the total number of CPUs supported (but not necessarily
113 val cpumaplen : int -> int
114 (** Calculate the length (in bytes) required to store the complete
115 CPU map between a single virtual and all physical CPUs of a domain.
118 val use_cpu : string -> int -> unit
119 (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
120 val unuse_cpu : string -> int -> unit
121 (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
122 val cpu_usable : string -> int -> int -> int -> bool
123 (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
124 [cpu] is usable by [vcpu]. *)
126 external const : [>`R] t -> ro t = "%identity"
127 (** [const conn] turns a read/write connection into a read-only
128 connection. Note that the opposite operation is impossible.
131 (** Module dealing with connections. [Connect.t] is the
138 (** Domain handle. Read-only handles have type [ro Domain.t] and
139 read-write handles have type [rw Domain.t].
143 | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
144 | InfoShutdown | InfoShutoff | InfoCrashed
147 state : state; (** running state *)
148 max_mem : int64; (** maximum memory in kilobytes *)
149 memory : int64; (** memory used in kilobytes *)
150 nr_virt_cpu : int; (** number of virtual CPUs *)
151 cpu_time : int64; (** CPU time used in nanoseconds *)
154 type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
157 number : int; (** virtual CPU number *)
158 vcpu_state : vcpu_state; (** state *)
159 vcpu_time : int64; (** CPU time used in nanoseconds *)
160 cpu : int; (** real CPU number, -1 if offline *)
163 type sched_param = string * sched_param_value
164 and sched_param_value =
165 | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
166 | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
167 | SchedFieldFloat of float | SchedFieldBool of bool
169 type migrate_flag = Live
179 type interface_stats = {
190 val create_linux : [>`W] Connect.t -> xml -> rw t
191 val lookup_by_id : 'a Connect.t -> int -> 'a t
192 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
193 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
194 val lookup_by_name : 'a Connect.t -> string -> 'a t
195 val destroy : [>`W] t -> unit
196 val free : [>`R] t -> unit
197 (** [free domain] frees the domain object in memory.
199 The domain object is automatically freed if it is garbage
200 collected. This function just forces it to be freed right
204 val suspend : [>`W] t -> unit
205 val resume : [>`W] t -> unit
206 val save : [>`W] t -> string -> unit
207 val restore : [>`W] Connect.t -> string -> unit
208 val core_dump : [>`W] t -> string -> unit
209 val shutdown : [>`W] t -> unit
210 val reboot : [>`W] t -> unit
211 val get_name : [>`R] t -> string
212 val get_uuid : [>`R] t -> uuid
213 val get_uuid_string : [>`R] t -> string
214 val get_id : [>`R] t -> int
215 (** [getid dom] returns the ID of the domain.
217 Do not call this on a defined but not running domain. Those
218 domains don't have IDs, and you'll get an error here.
221 val get_os_type : [>`R] t -> string
222 val get_max_memory : [>`R] t -> int64
223 val set_max_memory : [>`W] t -> int64 -> unit
224 val set_memory : [>`W] t -> int64 -> unit
225 val get_info : [>`R] t -> info
226 val get_xml_desc : [>`R] t -> xml
227 val get_scheduler_type : [>`R] t -> string * int
228 val get_scheduler_parameters : [>`R] t -> int -> sched_param array
229 val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
230 val define_xml : [>`W] Connect.t -> xml -> rw t
231 val undefine : [>`W] t -> unit
232 val create : [>`W] t -> unit
233 val get_autostart : [>`R] t -> bool
234 val set_autostart : [>`W] t -> bool -> unit
235 val set_vcpus : [>`W] t -> int -> unit
236 val pin_vcpu : [>`W] t -> int -> string -> unit
237 val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
238 val get_max_vcpus : [>`R] t -> int
239 val attach_device : [>`W] t -> xml -> unit
240 val detach_device : [>`W] t -> xml -> unit
242 val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
243 ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
245 val block_stats : [>`R] t -> string -> block_stats
246 val interface_stats : [>`R] t -> string -> interface_stats
248 external const : [>`R] t -> ro t = "%identity"
249 (** [const dom] turns a read/write domain handle into a read-only
250 domain handle. Note that the opposite operation is impossible.
253 (** Module dealing with domains. [Domain.t] is the
260 (** Network handle. Read-only handles have type [ro Network.t] and
261 read-write handles have type [rw Network.t].
264 val lookup_by_name : 'a Connect.t -> string -> 'a t
265 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
266 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
267 val create_xml : [>`W] Connect.t -> xml -> rw t
268 val define_xml : [>`W] Connect.t -> xml -> rw t
269 val undefine : [>`W] t -> unit
270 val create : [>`W] t -> unit
271 val destroy : [>`W] t -> unit
272 val free : [>`R] t -> unit
273 (** [free network] frees the network object in memory.
275 The network object is automatically freed if it is garbage
276 collected. This function just forces it to be freed right
280 val get_name : [>`R] t -> string
281 val get_uuid : [>`R] t -> uuid
282 val get_uuid_string : [>`R] t -> string
283 val get_xml_desc : [>`R] t -> xml
284 val get_bridge_name : [>`R] t -> string
285 val get_autostart : [>`R] t -> bool
286 val set_autostart : [>`W] t -> bool -> unit
288 external const : [>`R] t -> ro t = "%identity"
289 (** [const network] turns a read/write network handle into a read-only
290 network handle. Note that the opposite operation is impossible.
293 (** Module dealing with networks. [Network.t] is the
301 | VIR_ERR_INTERNAL_ERROR
304 | VIR_ERR_UNKNOWN_HOST
306 | VIR_ERR_INVALID_CONN
307 | VIR_ERR_INVALID_DOMAIN
308 | VIR_ERR_INVALID_ARG
309 | VIR_ERR_OPERATION_FAILED
311 | VIR_ERR_POST_FAILED
313 | VIR_ERR_SEXPR_SERIAL
324 | VIR_ERR_NO_XENSTORE
325 | VIR_ERR_DRIVER_FULL
326 | VIR_ERR_CALL_FAILED
329 | VIR_ERR_OPERATION_DENIED
330 | VIR_ERR_OPEN_FAILED
331 | VIR_ERR_READ_FAILED
332 | VIR_ERR_PARSE_FAILED
333 | VIR_ERR_CONF_SYNTAX
334 | VIR_ERR_WRITE_FAILED
336 | VIR_ERR_INVALID_NETWORK
337 | VIR_ERR_NETWORK_EXIST
338 | VIR_ERR_SYSTEM_ERROR
340 | VIR_ERR_GNUTLS_ERROR
344 (** See [<libvirt/virterror.h>] for meaning of these codes. *)
346 val string_of_code : code -> string
352 (** No error, a warning or an error. *)
354 val string_of_level : level -> string
371 (** Subsystem / driver which produced the error. *)
373 val string_of_domain : domain -> string
376 code : code; (** Error code. *)
377 domain : domain; (** Origin of the error. *)
378 message : string option; (** Human-readable message. *)
379 level : level; (** Error or warning. *)
380 conn : ro Connect.t option; (** Associated connection. *)
381 dom : ro Domain.t option; (** Associated domain. *)
382 str1 : string option; (** Informational string. *)
383 str2 : string option; (** Informational string. *)
384 str3 : string option; (** Informational string. *)
385 int1 : int32; (** Informational integer. *)
386 int2 : int32; (** Informational integer. *)
387 net : ro Network.t option; (** Associated network. *)
389 (** An error object. *)
391 val to_string : t -> string
392 (** Turn the exception into a printable string. *)
394 val get_last_error : unit -> t option
395 val get_last_conn_error : [>`R] Connect.t -> t option
396 (** Get the last error at a global or connection level.
398 Normally you do not need to use these functions because
399 the library automatically turns errors into exceptions.
402 val reset_last_error : unit -> unit
403 val reset_last_conn_error : [>`R] Connect.t -> unit
404 (** Reset the error at a global or connection level.
406 Normally you do not need to use these functions.
409 val no_error : unit -> t
410 (** Creates an empty error message.
412 Normally you do not need to use this function.
415 (** Module dealing with errors. *)
417 exception Virterror of Virterror.t
418 (** This exception can be raised by any library function that detects
419 an error. To get a printable error message, call
420 {!Virterror.to_string} on the content of this exception.
422 Note that functions may also raise
423 [Invalid_argument "virFoo not supported"]
424 (where virFoo is the libvirt function name) if a function is
425 not supported at either compile or runtime. This applies to
426 any libvirt function added after version 0.2.1.
427 See also [http://libvirt.org/hvsupport.html]