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