virt_mem_mmap.mli

   1 (* Memory info command for virtual domains.
   2    (C) Copyright 2008 Richard W.M. Jones, Red Hat Inc.
   3    http://libvirt.org/
   4
   5    This program is free software; you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation; either version 2 of the License, or
   8    (at your option) any later version.
   9
  10    This program is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program; if not, write to the Free Software
  17    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18
  19    Functions for making a memory map of a virtual machine from
  20    various sources.  The memory map will most certainly have holes.
  21  *)
  22
  23 type ('a,'b) t
  24 (** Memory map. *)
  25
  26 type addr = int64
  27 (** Virtual memory addresses (even on 32 bit machines). *)
  28
  29 val create : unit -> ([`NoWordsize], [`NoEndian]) t
  30 (** Create a new, empty memory map. *)
  31
  32 val set_wordsize : ([`NoWordsize], 'b) t -> Virt_mem_utils.wordsize ->
  33   ([`Wordsize], 'b) t
  34 (** Set the natural wordsize of the memory map.  This is used
  35     for matching pointers within the map and can be set only once. *)
  36
  37 val set_endian : ('a, [`NoEndian]) t -> Bitmatch.endian ->
  38   ('a, [`Endian]) t
  39 (** Set the natural endianness of the memory map.  This is used
  40     for matching pointers within the map and can be set only once. *)
  41
  42 val get_wordsize : ([`Wordsize], 'b) t -> Virt_mem_utils.wordsize
  43 (** Return the wordsize previously set for this memory map. *)
  44
  45 val get_endian : ('a, [`Endian]) t -> Bitmatch.endian
  46 (** Return the endianness previously set for this memory map. *)
  47
  48 val of_file : Unix.file_descr -> addr -> ([`NoWordsize], [`NoEndian]) t
  49 (** Create a new memory map, mapping file [fd] at address [addr]. *)
  50
  51 val add_file : ('a, 'b) t -> Unix.file_descr -> addr -> ('a, 'b) t
  52 (** Add file [fd] at address [addr] to an existing memory map.
  53     Behaviour is undefined if memory mappings overlap. *)
  54
  55 val find : ('a, 'b) t -> ?start:addr -> string -> addr option
  56 (** Find string in a memory map and return its address (if found).
  57     You can pass an optional starting address.  Any holes in
  58     the memory map are skipped automatically. *)
  59
  60 val find_align : ([`Wordsize], 'b) t -> ?start:addr -> string -> addr option
  61 (** Find a string aligned to the wordsize in the memory map. *)
  62
  63 val find_all : ('a, 'b) t -> ?start:addr -> string -> addr list
  64 (** Find all occurrences of a string in a memory map. *)
  65
  66 val find_all_align : ([`Wordsize], 'b) t -> ?start:addr -> string -> addr list
  67 (** Find all occurrences of a string in a memory map. *)
  68
  69 val find_pointer : ([`Wordsize], [`Endian]) t -> ?start:addr -> addr ->
  70   addr option
  71 (** Find a pointer (address) in the memory map.
  72     The pointer must be aligned to a word. *)
  73
  74 val find_pointer_all : ([`Wordsize], [`Endian]) t -> ?start:addr -> addr ->
  75   addr list
  76 (** Find all occurrences of a pointer in the memory map. *)
  77
  78 val get_byte : ('a, 'b) t -> addr -> int
  79 (** Return the byte at the given address.
  80
  81     This may raise [Invalid_argument "get_byte"] if the address is
  82     not mapped. *)
  83
  84 val get_bytes : ('a, 'b) t -> addr -> int -> string
  85 (** Return the sequence of bytes starting at the given address.
  86
  87     This may raise [Invalid_argument "get_bytes"] if the address range
  88     is not fully mapped. *)
  89
  90 val get_string : ('a, 'b) t -> addr -> string
  91 (** Return the sequence of bytes starting at [addr] up to (but not
  92     including) the first ASCII NUL character.  In other words, this
  93     returns a C-style string.
  94
  95     This may raise [Invalid_argument "get_string"] if we reach an
  96     unmapped address before finding the end of the string.
  97
  98     See also {!is_string} and {!is_C_identifier}. *)
  99
 100 val is_string : ('a, 'b) t -> addr -> bool
 101 (** Return true or false if the address contains an ASCII NUL-terminated
 102     string. *)
 103
 104 val is_C_identifier : ('a, 'b) t -> addr -> bool
 105 (** Return true or false if the address contains a NUL-terminated
 106     C identifier. *)
 107
 108 val follow_pointer : ([`Wordsize], [`Endian]) t -> addr -> addr
 109 (** Follow (dereference) the pointer at [addr] and return
 110     the address pointed to. *)
 111
 112 val succ_long : ([`Wordsize], 'b) t -> addr -> addr
 113 (** Add wordsize bytes to [addr] and return it. *)
 114
 115 val pred_long : ([`Wordsize], 'b) t -> addr -> addr
 116 (** Subtract wordsize bytes from [addr] and return it. *)