package mirage-block-unix

  1. Overview
  2. Docs
package mirage-block-unix
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module BlockSource

Block device on top of Lwt_unix

include Mirage_block.S
Sourcetype error = private [>
  1. | Mirage_device.error
]

The type for block errors.

Sourceval pp_error : error Fmt.t

pp_error is the pretty-printer for errors.

Sourcetype write_error = private [>
  1. | Mirage_device.error
  2. | `Is_read_only
]

The type for write errors.

Sourceval pp_write_error : write_error Fmt.t

pp_write_error is the pretty-printer for write errors.

include Mirage_device.S
Sourcetype t

The type representing the internal state of the device

Sourceval disconnect : t -> unit Lwt.t

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

Sourceval get_info : t -> Mirage_block.info Lwt.t

Query the characteristics of a specific block device

Sourceval read : t -> int64 -> Cstruct.t list -> (unit, error) result Lwt.t

read device sector_start buffers reads data starting at sector_start from the block device into buffers. Ok () means the buffers have been filled. Error _ indicates an I/O error has happened and some of the buffers may not be filled. Each of elements in the list buffers must be a whole number of sectors in length. The list of buffers can be of any length.

Sourceval write : t -> int64 -> Cstruct.t list -> (unit, write_error) result Lwt.t

write device sector_start buffers writes data from buffers onto the block device starting at sector_start. Ok () means the contents of the buffers have been written. Error _ indicates a partial failure in which some of the writes may not have happened.

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.

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

Sourceval really_read : Lwt_unix.file_descr -> Cstruct.t -> unit Lwt.t
Sourceval really_write : Lwt_unix.file_descr -> Cstruct.t -> unit Lwt.t
Sourceval blkgetsize : string -> Unix.file_descr -> (int64, error) result

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.

Sourceval ftruncate : Lwt_unix.file_descr -> int64 -> unit Lwt.t

ftruncate fd size: changes the size of the file backed by fd to size. This function works on Unix and Windows.

Sourcemodule Config : sig ... end
Sourceval connect : ?buffered:bool -> ?sync:Config.sync_behaviour option -> ?lock:bool -> string -> t Lwt.t

connect ?buffered ?sync ?lock path connects to a block device on the filesystem at path. By default I/O is buffered and asynchronous. By default the file is unlocked. These defaults can be changed by supplying the optional arguments ~buffered:false and ~sync:false ~lock:true

Sourceval resize : t -> int64 -> (unit, write_error) result Lwt.t

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.

Sourceval flush : t -> (unit, write_error) result Lwt.t

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

Sourceval seek_unmapped : t -> int64 -> (int64, error) result Lwt.t

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

Sourceval seek_mapped : t -> int64 -> (int64, error) result Lwt.t

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)

Sourceval discard : t -> int64 -> int64 -> (unit, write_error) result Lwt.t

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

Sourceval to_config : t -> Config.t

to_config t returns the configuration of a device

Sourceval of_config : Config.t -> t Lwt.t

of_config config creates a fresh device from config