1 (** OCaml bindings for libvirt.
2 (C) Copyright 2007 Richard W.M. Jones, Red Hat Inc.
4 $Id: libvirt.mli,v 1.3 2007/08/22 10:04:07 rjones Exp $
8 (** This is a "raw" UUID, ie. a packed string of bytes. *)
11 (** Type of XML (an uninterpreted string of bytes). Use PXP, expat,
12 xml-light, etc. if you want to do anything useful with the XML.
15 val get_version : ?driver:string -> unit -> int * int
16 (** [get_version ()] returns the library version in the first part
17 of the tuple, and [0] in the second part.
19 [get_version ~driver ()] returns the library version in the first
20 part of the tuple, and the version of the driver called [driver]
23 The version numbers are encoded as
24 1,000,000 * major + 1,000 * minor + release.
28 (** Length of packed UUIDs. *)
30 val uuid_string_length : int
31 (** Length of UUID strings. *)
33 (* These phantom types are used to ensure the type-safety of read-only
34 * versus read-write connections. For more information see:
35 * http://caml.inria.fr/pub/ml-archives/caml-list/2004/07/80683af867cce6bf8fff273973f70c95.en.html
43 (** Connection. Read-only connections have type [ro Connect.t] and
44 read-write connections have type [rw Connect.t].
48 model : string; (** CPU model *)
49 memory : int64; (** memory size in kilobytes *)
50 cpus : int; (** number of active CPUs *)
51 mhz : int; (** expected CPU frequency *)
52 nodes : int; (** number of NUMA nodes (1 = UMA) *)
53 sockets : int; (** number of CPU sockets per node *)
54 cores : int; (** number of cores per socket *)
55 threads : int; (** number of threads per core *)
58 val connect : ?name:string -> unit -> rw t
59 val connect_readonly : ?name:string -> unit -> ro t
60 (** [connect ~name ()] connects to the hypervisor with URI [name].
62 [connect ()] connects to the default hypervisor.
64 [connect_readonly] is the same but connects in read-only mode.
67 val close : [>`R] t -> unit
68 (** [close conn] closes and frees the connection object in memory.
70 The connection is automatically closed if it is garbage
71 collected. This function just forces it to be closed
75 val get_type : [>`R] t -> string
76 val get_version : [>`R] t -> int
77 val get_hostname : [>`R] t -> string
78 val get_uri : [>`R] t -> string
79 val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int
80 val list_domains : [>`R] t -> int -> int array
81 val num_of_domains : [>`R] t -> int
82 val get_capabilities : [>`R] t -> string
83 val num_of_defined_domains : [>`R] t -> int
84 val list_defined_domains : [>`R] t -> int -> string array
85 val num_of_networks : [>`R] t -> int
86 val list_networks : [>`R] t -> int -> string array
87 val num_of_defined_networks : [>`R] t -> int
88 val list_defined_networks : [>`R] t -> int -> string array
90 (* The name of this function is inconsistent, but the inconsistency
91 * is really in libvirt itself.
93 val get_node_info : [>`R] t -> node_info
95 val maxcpus_of_node_info : node_info -> int
96 (** Calculate the total number of CPUs supported (but not necessarily
100 val cpumaplen : int -> int
101 (** Calculate the length (in bytes) required to store the complete
102 CPU map between a single virtual and all physical CPUs of a domain.
105 val use_cpu : string -> int -> unit
106 (** [use_cpu cpumap cpu] marks [cpu] as usable in [cpumap]. *)
107 val unuse_cpu : string -> int -> unit
108 (** [unuse_cpu cpumap cpu] marks [cpu] as not usable in [cpumap]. *)
109 val cpu_usable : string -> int -> int -> int -> bool
110 (** [cpu_usable cpumaps maplen vcpu cpu] checks returns true iff the
111 [cpu] is usable by [vcpu]. *)
113 external const : [>`R] t -> ro t = "%identity"
114 (** [const conn] turns a read/write connection into a read-only
115 connection. Note that the opposite operation is impossible.
118 (** Module dealing with connections. [Connect.t] is the
125 (** Domain handle. Read-only handles have type [ro Domain.t] and
126 read-write handles have type [rw Domain.t].
130 | InfoNoState | InfoRunning | InfoBlocked | InfoPaused
131 | InfoShutdown | InfoShutoff | InfoCrashed
134 state : state; (** running state *)
135 max_mem : int64; (** maximum memory in kilobytes *)
136 memory : int64; (** memory used in kilobytes *)
137 nr_virt_cpu : int; (** number of virtual CPUs *)
138 cpu_time : int64; (** CPU time used in nanoseconds *)
141 type vcpu_state = VcpuOffline | VcpuRunning | VcpuBlocked
144 number : int; (** virtual CPU number *)
145 vcpu_state : vcpu_state; (** state *)
146 vcpu_time : int64; (** CPU time used in nanoseconds *)
147 cpu : int; (** real CPU number, -1 if offline *)
150 type sched_param = string * sched_param_value
151 and sched_param_value =
152 | SchedFieldInt32 of int32 | SchedFieldUInt32 of int32
153 | SchedFieldInt64 of int64 | SchedFieldUInt64 of int64
154 | SchedFieldFloat of float | SchedFieldBool of bool
156 type migrate_flag = Live
166 type interface_stats = {
177 val create_linux : [>`W] Connect.t -> xml -> rw t
178 val lookup_by_id : 'a Connect.t -> int -> 'a t
179 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
180 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
181 val lookup_by_name : 'a Connect.t -> string -> 'a t
182 val destroy : [>`W] t -> unit
183 val free : [>`R] t -> unit
184 (** [free domain] frees the domain object in memory.
186 The domain object is automatically freed if it is garbage
187 collected. This function just forces it to be freed right
191 val suspend : [>`W] t -> unit
192 val resume : [>`W] t -> unit
193 val save : [>`W] t -> string -> unit
194 val restore : [>`W] Connect.t -> string -> unit
195 val core_dump : [>`W] t -> string -> unit
196 val shutdown : [>`W] t -> unit
197 val reboot : [>`W] t -> unit
198 val get_name : [>`R] t -> string
199 val get_uuid : [>`R] t -> uuid
200 val get_uuid_string : [>`R] t -> string
201 val get_id : [>`R] t -> int
202 (** [getid dom] returns the ID of the domain.
204 Do not call this on a defined but not running domain. Those
205 domains don't have IDs, and you'll get an error here.
208 val get_os_type : [>`R] t -> string
209 val get_max_memory : [>`R] t -> int64
210 val set_max_memory : [>`W] t -> int64 -> unit
211 val set_memory : [>`W] t -> int64 -> unit
212 val get_info : [>`R] t -> info
213 val get_xml_desc : [>`R] t -> xml
214 val get_scheduler_type : [>`R] t -> string * int
215 val get_scheduler_parameters : [>`R] t -> int -> sched_param array
216 val set_scheduler_parameters : [>`W] t -> sched_param array -> unit
217 val define_xml : [>`W] Connect.t -> xml -> rw t
218 val undefine : [>`W] t -> unit
219 val create : [>`W] t -> unit
220 val get_autostart : [>`R] t -> bool
221 val set_autostart : [>`W] t -> bool -> unit
222 val set_vcpus : [>`W] t -> int -> unit
223 val pin_vcpu : [>`W] t -> int -> string -> unit
224 val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string
225 val get_max_vcpus : [>`R] t -> int
226 val attach_device : [>`W] t -> xml -> unit
227 val detach_device : [>`W] t -> xml -> unit
229 val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list ->
230 ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t
232 val block_stats : [>`R] t -> string -> block_stats
233 val interface_stats : [>`R] t -> string -> interface_stats
235 external const : [>`R] t -> ro t = "%identity"
236 (** [const dom] turns a read/write domain handle into a read-only
237 domain handle. Note that the opposite operation is impossible.
240 (** Module dealing with domains. [Domain.t] is the
247 (** Network handle. Read-only handles have type [ro Network.t] and
248 read-write handles have type [rw Network.t].
251 val lookup_by_name : 'a Connect.t -> string -> 'a t
252 val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t
253 val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t
254 val create_xml : [>`W] Connect.t -> xml -> rw t
255 val define_xml : [>`W] Connect.t -> xml -> rw t
256 val undefine : [>`W] t -> unit
257 val create : [>`W] t -> unit
258 val destroy : [>`W] t -> unit
259 val free : [>`R] t -> unit
260 (** [free network] frees the network object in memory.
262 The network object is automatically freed if it is garbage
263 collected. This function just forces it to be freed right
267 val get_name : [>`R] t -> string
268 val get_uuid : [>`R] t -> uuid
269 val get_uuid_string : [>`R] t -> string
270 val get_xml_desc : [>`R] t -> xml
271 val get_bridge_name : [>`R] t -> string
272 val get_autostart : [>`R] t -> bool
273 val set_autostart : [>`W] t -> bool -> unit
275 external const : [>`R] t -> ro t = "%identity"
276 (** [const network] turns a read/write network handle into a read-only
277 network handle. Note that the opposite operation is impossible.
280 (** Module dealing with networks. [Network.t] is the
288 | VIR_ERR_INTERNAL_ERROR
291 | VIR_ERR_UNKNOWN_HOST
293 | VIR_ERR_INVALID_CONN
294 | VIR_ERR_INVALID_DOMAIN
295 | VIR_ERR_INVALID_ARG
296 | VIR_ERR_OPERATION_FAILED
298 | VIR_ERR_POST_FAILED
300 | VIR_ERR_SEXPR_SERIAL
311 | VIR_ERR_NO_XENSTORE
312 | VIR_ERR_DRIVER_FULL
313 | VIR_ERR_CALL_FAILED
316 | VIR_ERR_OPERATION_DENIED
317 | VIR_ERR_OPEN_FAILED
318 | VIR_ERR_READ_FAILED
319 | VIR_ERR_PARSE_FAILED
320 | VIR_ERR_CONF_SYNTAX
321 | VIR_ERR_WRITE_FAILED
323 | VIR_ERR_INVALID_NETWORK
324 | VIR_ERR_NETWORK_EXIST
325 | VIR_ERR_SYSTEM_ERROR
327 | VIR_ERR_GNUTLS_ERROR
331 (** See [<libvirt/virterror.h>] for meaning of these codes. *)
333 val string_of_code : code -> string
339 (** No error, a warning or an error. *)
341 val string_of_level : level -> string
358 (** Subsystem / driver which produced the error. *)
360 val string_of_domain : domain -> string
363 code : code; (** Error code. *)
364 domain : domain; (** Origin of the error. *)
365 message : string option; (** Human-readable message. *)
366 level : level; (** Error or warning. *)
367 conn : ro Connect.t option; (** Associated connection. *)
368 dom : ro Domain.t option; (** Associated domain. *)
369 str1 : string option; (** Informational string. *)
370 str2 : string option; (** Informational string. *)
371 str3 : string option; (** Informational string. *)
372 int1 : int32; (** Informational integer. *)
373 int2 : int32; (** Informational integer. *)
374 net : ro Network.t option; (** Associated network. *)
376 (** An error object. *)
378 val to_string : t -> string
379 (** Turn the exception into a printable string. *)
381 val get_last_error : unit -> t option
382 val get_last_conn_error : [>`R] Connect.t -> t option
383 (** Get the last error at a global or connection level.
385 Normally you do not need to use these functions because
386 the library automatically turns errors into exceptions.
389 val reset_last_error : unit -> unit
390 val reset_last_conn_error : [>`R] Connect.t -> unit
391 (** Reset the error at a global or connection level.
393 Normally you do not need to use these functions.
396 val no_error : unit -> t
397 (** Creates an empty error message.
399 Normally you do not need to use this function.
402 (** Module dealing with errors. *)
404 exception Virterror of Virterror.t
405 (** This exception can be raised by any library function that detects
406 an error. To get a printable error message, call
407 {!Virterror.to_string} on the content of this exception.
409 Note that functions may also raise
410 [Invalid_argument "virFoo not supported"]
411 (where virFoo is the libvirt function name) if a function is
412 not supported at either compile or runtime. This applies to
413 any libvirt function added after version 0.2.1.
414 See also [http://libvirt.org/hvsupport.html]