virt-df/virt_df.mli

   1 (** 'df' command for virtual domains. *)
   2 (* (C) Copyright 2007-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
  20 (** This module (Virt_df) contains functions and values which are
  21     used throughout the plug-ins and main code.
  22 *)
  23
  24 val ( +* ) : int32 -> int32 -> int32
  25 val ( -* ) : int32 -> int32 -> int32
  26 val ( ** ) : int32 -> int32 -> int32
  27 val ( /* ) : int32 -> int32 -> int32
  28 val ( +^ ) : int64 -> int64 -> int64
  29 val ( -^ ) : int64 -> int64 -> int64
  30 val ( *^ ) : int64 -> int64 -> int64
  31 val ( /^ ) : int64 -> int64 -> int64
  32 (** int32 and int64 infix operators for convenience. *)
  33
  34 val debug : bool ref                    (** If true, emit debug info to stderr*)
  35 val uri : string option ref             (** Hypervisor/libvirt URI. *)
  36 val inodes : bool ref                   (** Display inodes. *)
  37 val human : bool ref                    (** Display human-readable. *)
  38 val all : bool ref                      (** Show all or just active domains. *)
  39 val test_files : string list ref        (** In test mode (-t) list of files. *)
  40 (** State of command line arguments. *)
  41
  42 (**
  43    {2 Domain/device model}
  44
  45    The "domain/device model" that we currently understand looks
  46    like this:
  47
  48 {v
  49 domains
  50   |
  51   \--- host partitions / disk image files
  52          ||
  53        guest block devices
  54          |
  55          +--> guest partitions (eg. using MBR)
  56          |      |
  57          \-(1)->+--- filesystems (eg. ext3)
  58                 |
  59                 \--- PVs for LVM
  60                        |||
  61                      VGs and LVs
  62 v}
  63
  64    (1) Filesystems and PVs may also appear directly on guest
  65    block devices.
  66
  67    Partition schemes (eg. MBR) and filesystems register themselves
  68    with this main module and they are queried first to get an idea
  69    of the physical devices, partitions and filesystems potentially
  70    available to the guest.
  71
  72    Volume management schemes (eg. LVM2) register themselves here
  73    and are called later with "spare" physical devices and partitions
  74    to see if they contain LVM data.  If this results in additional
  75    logical volumes then these are checked for filesystems.
  76
  77    Swap space is considered to be a dumb filesystem for the purposes
  78    of this discussion.
  79 *)
  80
  81 class virtual device :
  82   object
  83     method virtual name : string
  84     method virtual read : int64 -> int -> string
  85     method read_bitstring : int64 -> int -> string * int * int
  86     method virtual size : int64
  87   end
  88   (**
  89      A virtual (or physical!) device, encapsulating any translation
  90      that has to be done to access the device.  eg. For partitions
  91      there is a simple offset, but for LVM you may need complicated
  92      table lookups.
  93
  94      We keep the underlying file descriptors open for the duration
  95      of the program.  There aren't likely to be many of them, and
  96      the program is short-lived, and it's easier than trying to
  97      track which device is using what fd.  As a result, there is no
  98      need for any close/deallocation function.
  99
 100      Note the very rare use of OOP in OCaml!
 101   *)
 102
 103 class block_device : string ->
 104   object
 105     method name : string
 106     method read : int64 -> int -> string
 107     method read_bitstring : int64 -> int -> string * int * int
 108     method size : int64
 109   end
 110     (** A concrete device which just direct-maps a file or /dev device. *)
 111
 112 class offset_device : string -> int64 -> int64 -> device ->
 113   object
 114     method name : string
 115     method read : int64 -> int -> string
 116     method read_bitstring : int64 -> int -> string * int * int
 117     method size : int64
 118   end
 119     (** A concrete device which maps a linear part of an underlying device.
 120
 121         [new offset_device name start size dev] creates a new
 122         device which maps bytes from [start] to [start+size-1]
 123         of the underlying device [dev] (ie. in this device they
 124         appear as bytes [0] to [size-1]).
 125
 126         Useful for things like partitions.
 127     *)
 128
 129 val null_device : device
 130     (** The null device.  Any attempt to read generates an error. *)
 131
 132 type domain = {
 133   dom_name : string;                    (** Domain name. *)
 134   dom_id : int option;                  (** Domain ID (if running). *)
 135   dom_disks : disk list;                (** Domain disks. *)
 136   dom_lv_filesystems :
 137     (lv * filesystem) list;             (** Domain LV filesystems. *)
 138 }
 139 and disk = {
 140   d_type : string option;               (** The <disk type=...> *)
 141   d_device : string;                    (** The <disk device=...> (eg "disk") *)
 142   d_source : string;                    (** The <source file=... or dev> *)
 143   d_target : string;                    (** The <target dev=...> (eg "hda") *)
 144   d_dev : device;                       (** Disk device. *)
 145   d_content : disk_content;             (** What's on it. *)
 146 }
 147 and disk_content =
 148     [ `Filesystem of filesystem         (** Contains a direct filesystem. *)
 149     | `Partitions of partitions         (** Contains partitions. *)
 150     | `PhysicalVolume of pv             (** Contains an LVM PV. *)
 151     | `Unknown                          (** Not probed or unknown. *)
 152     ]
 153 and partitions = {
 154   parts_name : string;                  (** Name of partitioning scheme. *)
 155   parts : partition list;               (** Partitions. *)
 156 }
 157 and partition = {
 158   part_status : partition_status;       (** Bootable, etc. *)
 159   part_type : int;                      (** Partition filesystem type. *)
 160   part_dev : device;                    (** Partition device. *)
 161   part_content : partition_content;     (** What's on it. *)
 162 }
 163 and partition_status = Bootable | Nonbootable | Malformed | NullEntry
 164 and partition_content =
 165     [ `Filesystem of filesystem         (** Filesystem. *)
 166     | `PhysicalVolume of pv             (** Contains an LVM PV. *)
 167     | `Unknown                          (** Not probed or unknown. *)
 168     ]
 169 and filesystem = {
 170   fs_name : string;                     (** Name of filesystem. *)
 171   fs_block_size : int64;                (** Block size (bytes). *)
 172   fs_blocks_total : int64;              (** Total blocks. *)
 173   fs_is_swap : bool;                    (** If swap, following not valid. *)
 174   fs_blocks_reserved : int64;           (** Blocks reserved for super-user. *)
 175   fs_blocks_avail : int64;              (** Blocks free (available). *)
 176   fs_blocks_used : int64;               (** Blocks in use. *)
 177   fs_inodes_total : int64;              (** Total inodes. *)
 178   fs_inodes_reserved : int64;           (** Inodes reserved for super-user. *)
 179   fs_inodes_avail : int64;              (** Inodes free (available). *)
 180   fs_inodes_used : int64;               (** Inodes in use. *)
 181 }
 182 and pv = {
 183   lvm_plugin_id : lvm_plugin_id;        (** The LVM plug-in which detected
 184                                             this. *)
 185   pv_uuid : string;                     (** UUID. *)
 186 }
 187 and lv = {
 188   lv_dev : device;                      (** Logical volume device. *)
 189 }
 190
 191 and lvm_plugin_id
 192
 193 val string_of_partition : partition -> string
 194 val string_of_filesystem : filesystem -> string
 195 (** Convert a partition or filesystem struct to a string (for debugging). *)
 196
 197 val canonical_uuid : string -> string
 198 (** Convert a UUID which may contain '-' characters to canonical form. *)
 199
 200 (** {2 Plug-in registration functions} *)
 201
 202 val partition_type_register : string -> (device -> partitions) -> unit
 203 (** Register a partition probing plug-in. *)
 204
 205 val probe_for_partitions : device -> partitions option
 206 (** Do a partition probe on a device.  Returns [Some partitions] or [None]. *)
 207
 208 val filesystem_type_register : string -> (device -> filesystem) -> unit
 209 (** Register a filesystem probing plug-in. *)
 210
 211 val probe_for_filesystem : device -> filesystem option
 212 (** Do a filesystem probe on a device.  Returns [Some filesystem] or [None]. *)
 213
 214 val lvm_type_register :
 215   string -> (lvm_plugin_id -> device -> pv) -> (device list -> lv list) -> unit
 216 (** [lvm_type_register lvm_name probe_fn list_lvs_fn]
 217     registers a new LVM type.  [probe_fn] is a function which
 218     should probe a device to find out if it contains a PV.
 219     [list_lvs_fn] is a function which should take a list of
 220     devices (PVs) and construct a list of LV devices.
 221 *)
 222
 223 val probe_for_pv : device -> pv option
 224 (** Do a PV probe on a device.  Returns [Some pv] or [None]. *)
 225
 226 val list_lvs : lvm_plugin_id -> device list -> lv list
 227 (** Construct LV devices from a list of PVs. *)
 228
 229 (** {2 Utility functions} *)
 230
 231 val group_by : ?cmp:('a -> 'a -> int) -> ('a * 'b) list -> ('a * 'b list) list
 232 (** Group a sorted list of pairs by the first element of the pair. *)
 233
 234 val range : int -> int -> int list
 235 (** [range a b] returns the list of integers [a <= i < b].
 236     If [a >= b] then the empty list is returned.
 237 *)