package mirage-block-unix

  1. Overview
  2. Docs
On This Page
Legend:
Library
Module
Module type
Parameter
Class
Class type

Block device on top of Lwt_unix

include V1.BLOCK with type 'a io = 'a Lwt.t and type page_aligned_buffer = Cstruct.t
type page_aligned_buffer = Cstruct.t

The type for page-aligned memory buffers.

type error = [
  1. | `Unknown of string
    (*

    an undiagnosed error

    *)
  2. | `Unimplemented
    (*

    operation not yet implemented in the code

    *)
  3. | `Is_read_only
    (*

    you cannot write to a read/only instance

    *)
  4. | `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 = {
  1. read_write : bool;
    (*

    True if we can write, false if read/only

    *)
  2. sector_size : int;
    (*

    Octets per sector

    *)
  3. 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.

low-level convenience functions

val really_read : Lwt_unix.file_descr -> Cstruct.t -> unit Lwt.t
val really_write : Lwt_unix.file_descr -> Cstruct.t -> unit Lwt.t
val blkgetsize : string -> Unix.file_descr -> [ `Ok of int64 | `Error of error ]

blkgetsize path fd: returns the size of the open block device given by fd. path is only used to construct a human-readable error message.

val connect : string -> [ `Ok of t | `Error of error ] io
val resize : t -> int64 -> [ `Ok of unit | `Error of error ] io

resize t new_size_sectors attempts to resize the connected device to have the given number of sectors. If successful, subsequent calls to get_info will reflect the new size.

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

flush t flushes any buffers, if the file has been opened in buffered mode

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

seek_unmapped t start returns the sector offset of the next guaranteed zero-filled region (typically guaranteed because it is unmapped)

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

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

OCaml

Innovation. Community. Security.