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
-   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
@@ -126,9 +127,8 @@ v}
     {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
@@ -143,12 +143,6 @@ v}
     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
@@ -425,6 +419,8 @@ sig
 
   type migrate_flag = Live
 
+  type memory_flag = Virtual
+
   type block_stats = {
     rd_req : int64;
     rd_bytes : int64;
@@ -444,6 +440,11 @@ sig
     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.
@@ -566,6 +567,24 @@ sig
   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.
@@ -938,14 +957,11 @@ sig
     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. *)
-    net : ro Network.t option;         (** Associated network. *)
   }
     (** An error object. *)