qcow 0.7.0 · OCaml Package

Parameters

module B : Qcow_s.RESIZABLE_BLOCK

module Time : V1_LWT.TIME

Signature

include V1_LWT.BLOCK

type page_aligned_buffer = Cstruct.t

The type for page-aligned memory buffers.

type error = [

| `Unknown of string
(*
an undiagnosed error
*)
| `Unimplemented
(*
operation not yet implemented in the code
*)
| `Is_read_only
(*
you cannot write to a read/only instance
*)
| `Disconnected
(*
the device has been previously disconnected
*)

]

The type for IO operation errors.

include V1.DEVICE with type error := error with type 'a io = 'a Lwt.t

type 'a io = 'a Lwt.t

The type for potentially blocking I/O operation

type t

The type representing the internal state of the device

type id

This type is no longer used and will be removed once other * modules stop using it in their type signatures.

val disconnect : t -> unit io

Disconnect from the device. While this might take some time to complete, it can never result in an error.

type info = {

read_write : bool;
(*
True if we can write, false if read/only
*)
sector_size : int;
(*
Octets per sector
*)
size_sectors : int64;
(*
Total sectors per device
*)

}

Characteristics of the block device. Note some devices may be able to make themselves bigger over time.

val get_info : t -> info io

Query the characteristics of a specific block device

val read : 
  t ->
  int64 ->
  page_aligned_buffer list ->
  [ `Error of error | `Ok of unit ] io

read device sector_start buffers returns a blocking IO operation which attempts to fill buffers with data starting at sector_start. Each of buffers must be a whole number of sectors in length. The list of buffers can be of any length.

val write : 
  t ->
  int64 ->
  page_aligned_buffer list ->
  [ `Error of error | `Ok of unit ] io

write device sector_start buffers returns a blocking IO operation which attempts to write the data contained within buffers to t starting at sector_start. When the IO operation completes then all writes have been persisted.

Once submitted, it is not possible to cancel a request and there is no timeout.

The operation may fail with:

`Unimplemented: the operation has not been implemented, no data has been written.
`Is_read_only: the device is read-only, no data has been written.
`Disconnected: the device has been disconnected at application request, an unknown amount of data has been written.
`Unknown: some other permanent, fatal error (e.g. disk is on fire), where an unknown amount of data has been written.

Each of buffers must be a whole number of sectors in length. The list of buffers can be of any length.

The data will not be copied, so the supplied buffers must not be re-used until the IO operation completes.

module Config : sig ... end

module Stats : sig ... end

val create : 
  B.t ->
  size:int64 ->
  ?lazy_refcounts:bool ->
  ?config:Config.t ->
  unit ->
  [ `Ok of t | `Error of error ] io

create block ~size ?lazy_refcounts () initialises a qcow-formatted image on block with virtual size size in bytes. By default the file will use lazy refcounts, but this can be overriden by supplying ~lazy_refcounts:false

val connect : ?config:Config.t -> B.t -> [ `Ok of t | `Error of error ] io

connect ?config block connects to an existing qcow-formatted image on block.

val resize : 
  t ->
  new_size:int64 ->
  ?ignore_data_loss:bool ->
  unit ->
  [ `Ok of unit | `Error of error ] io

resize block new_size_bytes ?ignore_data_loss changes the size of the qcow-formatted image to new_size_bytes, rounded up to the next allocation unit. This function will fail with an error if the new size would be smaller than the old size as this would cause data loss, unless the argument ?ignore_data_loss is set to true.

type compact_result = {

copied : int64;
(*
number of sectors copied
*)
refs_updated : int64;
(*
number of cluster references updated
*)
old_size : int64;
(*
previous size in sectors
*)
new_size : int64;
(*
new size in sectors
*)

}

Summary of the compaction run

val compact : 
  t ->
  ?progress_cb:(percent:int -> unit) ->
  unit ->
  [ `Ok of compact_result | `Error of error ] io

compact t () scans the disk for unused space and attempts to fill it and shrink the file. This is useful if the underlying block device doesn't support discard and we must emulate it.

val discard : 
  t ->
  sector:int64 ->
  n:int64 ->
  unit ->
  [ `Ok of unit | `Error of error ] io

discard sector n signals that the n sectors starting at sector are no longer needed and the contents may be discarded. Note the contents may not actually be deleted: this is not a "secure erase".

val seek_unmapped : t -> int64 -> [ `Ok of int64 | `Error of error ] io

seek_unmapped t start returns the offset of the next "hole": a region of the device which is guaranteed to be full of zeroes (typically guaranteed because it is unmapped)

val seek_mapped : t -> int64 -> [ `Ok of int64 | `Error of error ] io

seek_mapped t start returns the offset of the next region of the device which may have data in it (typically this is the next mapped region)

val rebuild_refcount_table : t -> [ `Ok of unit | `Error of error ] io

rebuild_refcount_table t rebuilds the refcount table from scratch. Normally we won't update the refcount table live, for performance.

type check_result = {

free : int64;
(*
unused sectors
*)
used : int64;
(*
used sectors
*)

}

val check : t -> [ `Ok of check_result | `Error of error ] io

check t performs sanity checks of the file, looking for errors

val header : t -> Header.t

Return a snapshot of the current header

val to_config : t -> Config.t

to_config t returns the configuration of a device

val get_stats : t -> Stats.t

get_stats t returns the runtime statistics of a device

module Debug : Qcow_s.DEBUG with type t = t and type error = error

package qcow

Parameters

Signature