Add Domain.max_peek function to determine maximum size of

[ocaml-libvirt.git] / libvirt / libvirt.mli

diff --git a/libvirt/libvirt.mli b/libvirt/libvirt.mli
index af372af..ec945b7 100644 (file)
--- a/libvirt/libvirt.mli
+++ b/libvirt/libvirt.mli
@@ -5,7 +5,8 @@
    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
    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.
+   version 2 of the License, or (at your option) any later version,
+   with the OCaml linking exception described in ../COPYING.LIB.

 
    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
 
    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of


@@ -126,9 +127,8 @@ v}
     {3 General safety issues}
 
     Memory allocation / automatic garbage collection of all libvirt
     {3 General safety issues}
 
     Memory allocation / automatic garbage collection of all libvirt

-    objects should be completely safe (except in the specific
-    virterror case noted below).  If you find any safety issues or if your
-    pure OCaml program ever segfaults, please contact the author.
+    objects should be completely safe.  If you find any safety issues
+    or if your pure OCaml program ever segfaults, please contact the author.

 
     You can force a libvirt object to be freed early by calling
     the [close] function on the object.  This shouldn't affect
 
     You can force a libvirt object to be freed early by calling
     the [close] function on the object.  This shouldn't affect


@@ -143,12 +143,6 @@ v}
     Thus domain objects can through odd exceptions at any time.
     This is just the nature of virtualisation.
 
     Thus domain objects can through odd exceptions at any time.
     This is just the nature of virtualisation.
 

-    Virterror has a specific design error which means that the
-    objects embedded in a virterror exception message are only
-    valid as long as the connection handle is still open.  This
-    is a design flaw in the C code of libvirt and we cannot fix
-    or work around it in the OCaml bindings.
-

     {3 Backwards and forwards compatibility}
 
     OCaml-libvirt is backwards and forwards compatible with
     {3 Backwards and forwards compatibility}
 
     OCaml-libvirt is backwards and forwards compatible with


@@ -425,6 +419,8 @@ sig
 
   type migrate_flag = Live
 
 
   type migrate_flag = Live
 

+  type memory_flag = Virtual
+

   type block_stats = {
     rd_req : int64;
     rd_bytes : int64;
   type block_stats = {
     rd_req : int64;
     rd_bytes : int64;


@@ -444,6 +440,11 @@ sig
     tx_drop : int64;
   }
 
     tx_drop : int64;
   }
 

+  val max_peek : [>`R] t -> int
+    (** Maximum size supported by the {!block_peek} and {!memory_peek}
+       functions.  If you want to peek more than this then you must
+       break your request into chunks. *)
+

   val create_linux : [>`W] Connect.t -> xml -> rw t
     (** Create a new guest domain (not necessarily a Linux one)
        from the given XML.
   val create_linux : [>`W] Connect.t -> xml -> rw t
     (** Create a new guest domain (not necessarily a Linux one)
        from the given XML.


@@ -566,6 +567,24 @@ sig
   val interface_stats : [>`R] t -> string -> interface_stats
     (** Returns network interface stats. *)
 
   val interface_stats : [>`R] t -> string -> interface_stats
     (** Returns network interface stats. *)
 

+  val block_peek : [>`R] t -> string -> int64 -> int -> string -> int -> unit
+    (** [block_peek dom path offset size buf boff] reads [size] bytes at
+       [offset] in the domain's [path] block device.
+
+       If successful then the data is written into [buf] starting
+       at offset [boff], for [size] bytes.
+
+       See also {!max_peek}. *)
+  val memory_peek : [>`R] t -> memory_flag list -> int64 -> int ->
+    string -> int -> unit
+    (** [memory_peek dom Virtual offset size] reads [size] bytes
+       at [offset] in the domain's virtual memory.
+
+       If successful then the data is written into [buf] starting
+       at offset [boff], for [size] bytes.
+
+       See also {!max_peek}. *)
+

   external const : [>`R] t -> ro t = "%identity"
     (** [const dom] turns a read/write domain handle into a read-only
        domain handle.  Note that the opposite operation is impossible.
   external const : [>`R] t -> ro t = "%identity"
     (** [const dom] turns a read/write domain handle into a read-only
        domain handle.  Note that the opposite operation is impossible.


@@ -938,14 +957,11 @@ sig
     domain : domain;                   (** Origin of the error. *)
     message : string option;           (** Human-readable message. *)
     level : level;                     (** Error or warning. *)
     domain : domain;                   (** Origin of the error. *)
     message : string option;           (** Human-readable message. *)
     level : level;                     (** Error or warning. *)

-    conn : ro Connect.t option;                (** Associated connection. *)
-    dom : ro Domain.t option;          (** Associated domain. *)

     str1 : string option;              (** Informational string. *)
     str2 : string option;              (** Informational string. *)
     str3 : string option;              (** Informational string. *)
     int1 : int32;                      (** Informational integer. *)
     int2 : int32;                      (** Informational integer. *)
     str1 : string option;              (** Informational string. *)
     str2 : string option;              (** Informational string. *)
     str3 : string option;              (** Informational string. *)
     int1 : int32;                      (** Informational integer. *)
     int2 : int32;                      (** Informational integer. *)

-    net : ro Network.t option;         (** Associated network. *)

   }
     (** An error object. *)
 
   }
     (** An error object. *)