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 :
 104   string ->
 105   object
 106     method name : string
 107     method read : int64 -> int -> string
 108     method read_bitstring : int64 -> int -> string * int * int
 109     method size : int64
 110   end
 111     (** A concrete device which just direct-maps a file or /dev device. *)
 112
 113 val null_device : device
 114     (** The null device.  Any attempt to read generates an error. *)
 115
 116 type domain = {
 117   dom_name : string;                    (** Domain name. *)
 118   dom_id : int option;                  (** Domain ID (if running). *)
 119   dom_disks : disk list;                (** Domain disks. *)
 120   dom_lv_filesystems : filesystem list; (** Domain LV filesystems. *)
 121 }
 122 and disk = {
 123   d_type : string option;               (** The <disk type=...> *)
 124   d_device : string;                    (** The <disk device=...> (eg "disk") *)
 125   d_source : string;                    (** The <source file=... or dev> *)
 126   d_target : string;                    (** The <target dev=...> (eg "hda") *)
 127   d_dev : device;                       (** Disk device. *)
 128   d_content : disk_content;             (** What's on it. *)
 129 }
 130 and disk_content =
 131     [ `Filesystem of filesystem         (** Contains a direct filesystem. *)
 132     | `Partitions of partitions         (** Contains partitions. *)
 133     | `PhysicalVolume of pv             (** Contains an LVM PV. *)
 134     | `Unknown                          (** Not probed or unknown. *)
 135     ]
 136 and partitions = {
 137   parts_name : string;                  (** Name of partitioning scheme. *)
 138   parts : partition list;               (** Partitions. *)
 139 }
 140 and partition = {
 141   part_status : partition_status;       (** Bootable, etc. *)
 142   part_type : int;                      (** Partition filesystem type. *)
 143   part_dev : device;                    (** Partition device. *)
 144   part_content : partition_content;     (** What's on it. *)
 145 }
 146 and partition_status = Bootable | Nonbootable | Malformed | NullEntry
 147 and partition_content =
 148     [ `Filesystem of filesystem         (** Filesystem. *)
 149     | `PhysicalVolume of pv             (** Contains an LVM PV. *)
 150     | `Unknown                          (** Not probed or unknown. *)
 151     ]
 152 and filesystem = {
 153   fs_name : string;                     (** Name of filesystem. *)
 154   fs_block_size : int64;                (** Block size (bytes). *)
 155   fs_blocks_total : int64;              (** Total blocks. *)
 156   fs_is_swap : bool;                    (** If swap, following not valid. *)
 157   fs_blocks_reserved : int64;           (** Blocks reserved for super-user. *)
 158   fs_blocks_avail : int64;              (** Blocks free (available). *)
 159   fs_blocks_used : int64;               (** Blocks in use. *)
 160   fs_inodes_total : int64;              (** Total inodes. *)
 161   fs_inodes_reserved : int64;           (** Inodes reserved for super-user. *)
 162   fs_inodes_avail : int64;              (** Inodes free (available). *)
 163   fs_inodes_used : int64;               (** Inodes in use. *)
 164 }
 165 and pv = {
 166   lvm_plugin_id : lvm_plugin_id;        (** The LVM plug-in which detected
 167                                             this. *)
 168   pv_uuid : string;                     (** UUID. *)
 169 }
 170 and lv = {
 171   lv_dev : device;                      (** Logical volume device. *)
 172 }
 173
 174 and lvm_plugin_id
 175
 176 val string_of_partition : partition -> string
 177 val string_of_filesystem : filesystem -> string
 178 (** Convert a partition or filesystem struct to a string (for debugging). *)
 179
 180 (** {2 Plug-in registration functions} *)
 181
 182 val partition_type_register : string -> (device -> partitions) -> unit
 183 (** Register a partition probing plug-in. *)
 184
 185 val probe_for_partitions : device -> partitions option
 186 (** Do a partition probe on a device.  Returns [Some partitions] or [None]. *)
 187
 188 val filesystem_type_register : string -> (device -> filesystem) -> unit
 189 (** Register a filesystem probing plug-in. *)
 190
 191 val probe_for_filesystem : device -> filesystem option
 192 (** Do a filesystem probe on a device.  Returns [Some filesystem] or [None]. *)
 193
 194 val lvm_type_register :
 195   string -> (lvm_plugin_id -> device -> pv) -> (device list -> lv list) -> unit
 196 (** [lvm_type_register lvm_name probe_fn list_lvs_fn]
 197     registers a new LVM type.  [probe_fn] is a function which
 198     should probe a device to find out if it contains a PV.
 199     [list_lvs_fn] is a function which should take a list of
 200     devices (PVs) and construct a list of LV devices.
 201 *)
 202
 203 val probe_for_pv : device -> pv option
 204 (** Do a PV probe on a device.  Returns [Some pv] or [None]. *)
 205
 206 val list_lvs : lvm_plugin_id -> device list -> lv list
 207 (** Construct LV devices from a list of PVs. *)
 208
 209 (** {2 Utility functions} *)
 210
 211 val group_by : ?cmp:('a -> 'a -> int) -> ('a * 'b) list -> ('a * 'b list) list
 212 (** Group a sorted list of pairs by the first element of the pair. *)
 213
 214 val range : int -> int -> int list
 215 (** [range a b] returns the list of integers [a <= i < b].
 216     If [a >= b] then the empty list is returned.
 217 *)