Move libraries into subdirectory, programs into their own subdirs.

[virt-mem.git] / lib / virt_mem_mmap.mli

diff --git a/lib/virt_mem_mmap.mli b/lib/virt_mem_mmap.mli
new file mode 100644 (file)
index 0000000..06de86a
--- /dev/null
+++ b/lib/virt_mem_mmap.mli
@@ -0,0 +1,116 @@
+(* Memory info command for virtual domains.
+   (C) Copyright 2008 Richard W.M. Jones, Red Hat Inc.
+   http://libvirt.org/
+
+   This program is free software; you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation; either version 2 of the License, or
+   (at your option) any later version.
+
+   This program 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 General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, write to the Free Software
+   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+   Functions for making a memory map of a virtual machine from
+   various sources.  The memory map will most certainly have holes.
+ *)
+
+type ('a,'b) t
+(** Memory map. *)
+
+type addr = int64
+(** Virtual memory addresses (even on 32 bit machines). *)
+
+val create : unit -> ([`NoWordsize], [`NoEndian]) t
+(** Create a new, empty memory map. *)
+
+val set_wordsize : ([`NoWordsize], 'b) t -> Virt_mem_utils.wordsize ->
+  ([`Wordsize], 'b) t
+(** Set the natural wordsize of the memory map.  This is used
+    for matching pointers within the map and can be set only once. *)
+
+val set_endian : ('a, [`NoEndian]) t -> Bitmatch.endian ->
+  ('a, [`Endian]) t
+(** Set the natural endianness of the memory map.  This is used
+    for matching pointers within the map and can be set only once. *)
+
+val get_wordsize : ([`Wordsize], 'b) t -> Virt_mem_utils.wordsize
+(** Return the wordsize previously set for this memory map. *)
+
+val get_endian : ('a, [`Endian]) t -> Bitmatch.endian
+(** Return the endianness previously set for this memory map. *)
+
+val of_file : Unix.file_descr -> addr -> ([`NoWordsize], [`NoEndian]) t
+(** Create a new memory map, mapping file [fd] at address [addr]. *)
+
+val add_file : ('a, 'b) t -> Unix.file_descr -> addr -> ('a, 'b) t
+(** Add file [fd] at address [addr] to an existing memory map.
+    Behaviour is undefined if memory mappings overlap. *)
+
+val find : ('a, 'b) t -> ?start:addr -> string -> addr option
+(** Find string in a memory map and return its address (if found).
+    You can pass an optional starting address.  Any holes in
+    the memory map are skipped automatically. *)
+
+val find_align : ([`Wordsize], 'b) t -> ?start:addr -> string -> addr option
+(** Find a string aligned to the wordsize in the memory map. *)
+
+val find_all : ('a, 'b) t -> ?start:addr -> string -> addr list
+(** Find all occurrences of a string in a memory map. *)
+
+val find_all_align : ([`Wordsize], 'b) t -> ?start:addr -> string -> addr list
+(** Find all occurrences of a string in a memory map. *)
+
+val find_pointer : ([`Wordsize], [`Endian]) t -> ?start:addr -> addr ->
+  addr option
+(** Find a pointer (address) in the memory map.
+    The pointer must be aligned to a word. *)
+
+val find_pointer_all : ([`Wordsize], [`Endian]) t -> ?start:addr -> addr ->
+  addr list
+(** Find all occurrences of a pointer in the memory map. *)
+
+val get_byte : ('a, 'b) t -> addr -> int
+(** Return the byte at the given address.
+
+    This may raise [Invalid_argument "get_byte"] if the address is
+    not mapped. *)
+
+val get_bytes : ('a, 'b) t -> addr -> int -> string
+(** Return the sequence of bytes starting at the given address.
+
+    This may raise [Invalid_argument "get_bytes"] if the address range
+    is not fully mapped. *)
+
+val get_string : ('a, 'b) t -> addr -> string
+(** Return the sequence of bytes starting at [addr] up to (but not
+    including) the first ASCII NUL character.  In other words, this
+    returns a C-style string.
+
+    This may raise [Invalid_argument "get_string"] if we reach an
+    unmapped address before finding the end of the string.
+
+    See also {!is_string} and {!is_C_identifier}. *)
+
+val is_string : ('a, 'b) t -> addr -> bool
+(** Return true or false if the address contains an ASCII NUL-terminated
+    string. *)
+
+val is_C_identifier : ('a, 'b) t -> addr -> bool
+(** Return true or false if the address contains a NUL-terminated
+    C identifier. *)
+
+val follow_pointer : ([`Wordsize], [`Endian]) t -> addr -> addr
+(** Follow (dereference) the pointer at [addr] and return
+    the address pointed to. *)
+
+val succ_long : ([`Wordsize], 'b) t -> addr -> addr
+(** Add wordsize bytes to [addr] and return it. *)
+
+val pred_long : ([`Wordsize], 'b) t -> addr -> addr
+(** Subtract wordsize bytes from [addr] and return it. *)