X-Git-Url: http://git.annexia.org/?p=virt-top.git;a=blobdiff_plain;f=libvirt%2Flibvirt.mli;h=58198c8e6c8f416b2adc62578543f33288a8441c;hp=8225bdac43536636a116e0e945acd1224198eff4;hb=40cca545e1e010e8ee1a4ed4e9636b7c0119d5a2;hpb=0e09861c06a0c274bcfdacceaee347f8aaa969cb diff --git a/libvirt/libvirt.mli b/libvirt/libvirt.mli old mode 100644 new mode 100755 index 8225bda..58198c8 --- a/libvirt/libvirt.mli +++ b/libvirt/libvirt.mli @@ -1,6 +1,20 @@ (** OCaml bindings for libvirt. (C) Copyright 2007 Richard W.M. Jones, Red Hat Inc. http://libvirt.org/ + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA *) type uuid = string @@ -11,6 +25,9 @@ type xml = string xml-light, etc. if you want to do anything useful with the XML. *) +type filename = string +(** A filename. *) + val get_version : ?driver:string -> unit -> int * int (** [get_version ()] returns the library version in the first part of the tuple, and [0] in the second part. @@ -72,24 +89,74 @@ sig *) val get_type : [>`R] t -> string + (** Returns the name of the driver (hypervisor). *) + val get_version : [>`R] t -> int + (** Returns the driver version + [major * 1_000_000 + minor * 1000 + release] + *) val get_hostname : [>`R] t -> string + (** Returns the hostname of the physical server. *) val get_uri : [>`R] t -> string + (** Returns the canonical connection URI. *) val get_max_vcpus : [>`R] t -> ?type_:string -> unit -> int + (** Returns the maximum number of virtual CPUs + supported by a guest VM of a particular type. *) val list_domains : [>`R] t -> int -> int array + (** [list_domains conn max] returns the running domain IDs, + up to a maximum of [max] entries. + Call {!num_of_domains} first to get a value for [max]. + *) val num_of_domains : [>`R] t -> int - val get_capabilities : [>`R] t -> string + (** Returns the number of running domains. *) + val get_capabilities : [>`R] t -> xml + (** Returns the hypervisor capabilities (as XML). *) val num_of_defined_domains : [>`R] t -> int + (** Returns the number of inactive (shutdown) domains. *) val list_defined_domains : [>`R] t -> int -> string array + (** [list_defined_domains conn max] + returns the names of the inactive domains, up to + a maximum of [max] entries. + Call {!num_of_defined_domains} first to get a value for [max]. + *) val num_of_networks : [>`R] t -> int + (** Returns the number of networks. *) val list_networks : [>`R] t -> int -> string array + (** [list_networks conn max] + returns the names of the networks, up to a maximum + of [max] entries. + Call {!num_of_networks} first to get a value for [max]. + *) val num_of_defined_networks : [>`R] t -> int + (** Returns the number of inactive networks. *) val list_defined_networks : [>`R] t -> int -> string array + (** [list_defined_networks conn max] + returns the names of the inactive networks, up to a maximum + of [max] entries. + Call {!num_of_defined_networks} first to get a value for [max]. + *) (* The name of this function is inconsistent, but the inconsistency * is really in libvirt itself. *) val get_node_info : [>`R] t -> node_info + (** Return information about the physical server. *) + + val node_get_free_memory : [> `R] t -> int64 + (** + [node_get_free_memory conn] + returns the amount of free memory (not allocated to any guest) + in the machine. + *) + + val node_get_cells_free_memory : [> `R] t -> int -> int -> int64 array + (** + [node_get_cells_free_memory conn start max] + returns the amount of free memory on each NUMA cell in kilobytes. + [start] is the first cell for which we return free memory. + [max] is the maximum number of cells for which we return free memory. + Returns an array of up to [max] entries in length. + *) val maxcpus_of_node_info : node_info -> int (** Calculate the total number of CPUs supported (but not necessarily @@ -174,11 +241,19 @@ sig } val create_linux : [>`W] Connect.t -> xml -> rw t + (** Create a new guest domain (not necessarily a Linux one) + from the given XML. + *) val lookup_by_id : 'a Connect.t -> int -> 'a t + (** Lookup a domain by ID. *) val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t + (** Lookup a domain by UUID. This uses the packed byte array UUID. *) val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t + (** Lookup a domain by (string) UUID. *) val lookup_by_name : 'a Connect.t -> string -> 'a t + (** Lookup a domain by name. *) val destroy : [>`W] t -> unit + (** Abruptly destroy a domain. *) val free : [>`R] t -> unit (** [free domain] frees the domain object in memory. @@ -188,15 +263,25 @@ sig *) val suspend : [>`W] t -> unit + (** Suspend a domain. *) val resume : [>`W] t -> unit - val save : [>`W] t -> string -> unit - val restore : [>`W] Connect.t -> string -> unit - val core_dump : [>`W] t -> string -> unit + (** Resume a domain. *) + val save : [>`W] t -> filename -> unit + (** Suspend a domain, then save it to the file. *) + val restore : [>`W] Connect.t -> filename -> unit + (** Restore a domain from a file. *) + val core_dump : [>`W] t -> filename -> unit + (** Force a domain to core dump to the named file. *) val shutdown : [>`W] t -> unit + (** Shutdown a domain. *) val reboot : [>`W] t -> unit + (** Reboot a domain. *) val get_name : [>`R] t -> string + (** Get the domain name. *) val get_uuid : [>`R] t -> uuid + (** Get the domain UUID (as a packed byte array). *) val get_uuid_string : [>`R] t -> string + (** Get the domain UUID (as a printable string). *) val get_id : [>`R] t -> int (** [getid dom] returns the ID of the domain. @@ -205,31 +290,67 @@ sig *) val get_os_type : [>`R] t -> string + (** Get the operating system type. *) val get_max_memory : [>`R] t -> int64 + (** Get the maximum memory allocation. *) val set_max_memory : [>`W] t -> int64 -> unit + (** Set the maximum memory allocation. *) val set_memory : [>`W] t -> int64 -> unit + (** Set the normal memory allocation. *) val get_info : [>`R] t -> info + (** Get information about a domain. *) val get_xml_desc : [>`R] t -> xml + (** Get the XML description of a domain. *) val get_scheduler_type : [>`R] t -> string * int + (** Get the scheduler type. *) val get_scheduler_parameters : [>`R] t -> int -> sched_param array + (** Get the array of scheduler parameters. *) val set_scheduler_parameters : [>`W] t -> sched_param array -> unit + (** Set the array of scheduler parameters. *) val define_xml : [>`W] Connect.t -> xml -> rw t + (** Define a new domain (but don't start it up) from the XML. *) val undefine : [>`W] t -> unit + (** Undefine a domain - removes its configuration. *) val create : [>`W] t -> unit + (** Launch a defined (inactive) domain. *) val get_autostart : [>`R] t -> bool + (** Get the autostart flag for a domain. *) val set_autostart : [>`W] t -> bool -> unit + (** Set the autostart flag for a domain. *) val set_vcpus : [>`W] t -> int -> unit + (** Change the number of vCPUs available to a domain. *) val pin_vcpu : [>`W] t -> int -> string -> unit + (** [pin_vcpu dom vcpu bitmap] pins a domain vCPU to a bitmap of physical + CPUs. See the libvirt documentation for details of the + layout of the bitmap. *) val get_vcpus : [>`R] t -> int -> int -> int * vcpu_info array * string + (** [get_vcpus dom maxinfo maplen] returns the pinning information + for a domain. See the libvirt documentation for details + of the array and bitmap returned from this function. + *) val get_max_vcpus : [>`R] t -> int + (** Returns the maximum number of vCPUs supported for this domain. *) val attach_device : [>`W] t -> xml -> unit + (** Attach a device (described by the device XML) to a domain. *) val detach_device : [>`W] t -> xml -> unit + (** Detach a device (described by the device XML) from a domain. *) val migrate : [>`W] t -> [>`W] Connect.t -> migrate_flag list -> ?dname:string -> ?uri:string -> ?bandwidth:int -> unit -> rw t + (** [migrate dom dconn flags ()] migrates a domain to a + destination host described by [dconn]. + + The optional flag [?dname] is used to rename the domain. + + The optional flag [?uri] is used to route the migration. + + The optional flag [?bandwidth] is used to limit the bandwidth + used for migration (in Mbps). *) val block_stats : [>`R] t -> string -> block_stats + (** Returns block device stats. *) val interface_stats : [>`R] t -> string -> interface_stats + (** Returns network interface stats. *) external const : [>`R] t -> ro t = "%identity" (** [const dom] turns a read/write domain handle into a read-only @@ -248,13 +369,21 @@ sig *) val lookup_by_name : 'a Connect.t -> string -> 'a t + (** Lookup a network by name. *) val lookup_by_uuid : 'a Connect.t -> uuid -> 'a t + (** Lookup a network by (packed) UUID. *) val lookup_by_uuid_string : 'a Connect.t -> string -> 'a t + (** Lookup a network by UUID string. *) val create_xml : [>`W] Connect.t -> xml -> rw t + (** Create a network. *) val define_xml : [>`W] Connect.t -> xml -> rw t + (** Define but don't activate a network. *) val undefine : [>`W] t -> unit + (** Undefine configuration of a network. *) val create : [>`W] t -> unit + (** Start up a defined (inactive) network. *) val destroy : [>`W] t -> unit + (** Destroy a network. *) val free : [>`R] t -> unit (** [free network] frees the network object in memory. @@ -264,12 +393,19 @@ sig *) val get_name : [>`R] t -> string + (** Get network name. *) val get_uuid : [>`R] t -> uuid + (** Get network packed UUID. *) val get_uuid_string : [>`R] t -> string + (** Get network UUID as a printable string. *) val get_xml_desc : [>`R] t -> xml + (** Get XML description of a network. *) val get_bridge_name : [>`R] t -> string + (** Get bridge device name of a network. *) val get_autostart : [>`R] t -> bool + (** Get the autostart flag for a network. *) val set_autostart : [>`W] t -> bool -> unit + (** Set the autostart flag for a network. *) external const : [>`R] t -> ro t = "%identity" (** [const network] turns a read/write network handle into a read-only @@ -327,18 +463,13 @@ sig | VIR_WAR_NO_NETWORK | VIR_ERR_NO_DOMAIN | VIR_ERR_NO_NETWORK + | VIR_ERR_INVALID_MAC + (* ^^ NB: If you add a variant you MUST edit libvirt_c.c:MAX_VIR_* *) + | VIR_ERR_UNKNOWN of int (** See [] for meaning of these codes. *) val string_of_code : code -> string - type level = - | VIR_ERR_NONE - | VIR_ERR_WARNING - | VIR_ERR_ERROR - (** No error, a warning or an error. *) - - val string_of_level : level -> string - type domain = | VIR_FROM_NONE | VIR_FROM_XEN @@ -354,10 +485,25 @@ sig | VIR_FROM_NET | VIR_FROM_TEST | VIR_FROM_REMOTE + | VIR_FROM_OPENVZ + | VIR_FROM_XENXM + | VIR_FROM_STATS_LINUX + (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *) + | VIR_FROM_UNKNOWN of int (** Subsystem / driver which produced the error. *) val string_of_domain : domain -> string + type level = + | VIR_ERR_NONE + | VIR_ERR_WARNING + | VIR_ERR_ERROR + (* ^^ NB: If you add a variant you MUST edit libvirt_c.c: MAX_VIR_* *) + | VIR_ERR_UNKNOWN_LEVEL of int + (** No error, a warning or an error. *) + + val string_of_level : level -> string + type t = { code : code; (** Error code. *) domain : domain; (** Origin of the error. *) @@ -404,12 +550,16 @@ exception Virterror of Virterror.t (** This exception can be raised by any library function that detects an error. To get a printable error message, call {!Virterror.to_string} on the content of this exception. +*) - Note that functions may also raise - [Invalid_argument "virFoo not supported"] - (where virFoo is the libvirt function name) if a function is - not supported at either compile or runtime. This applies to +exception Not_supported of string +(** + Functions may raise + [Not_supported "virFoo"] + (where [virFoo] is the libvirt function name) if a function is + not supported at either compile or run time. This applies to any libvirt function added after version 0.2.1. + See also [http://libvirt.org/hvsupport.html] *)