package core

  1. Overview
  2. Docs
package core
Legend:
Library
Module
Module type
Parameter
Class
Class type

String type based on Bigarray, for use in I/O and C-bindings

include module type of struct include Core_kernel.Bigstring end

Types and exceptions

Type of bigstrings

include sig ... end
val bin_read_t : t Bin_prot.Read.reader
val __bin_read_t__ : (Base.Int.t -> t) Bin_prot.Read.reader
val bin_reader_t : t Bin_prot.Type_class.reader
val bin_size_t : t Bin_prot.Size.sizer
val bin_write_t : t Bin_prot.Write.writer
val bin_writer_t : t Bin_prot.Type_class.writer
val bin_shape_t : Bin_prot.Shape.t
val compare : t -> t -> Base.Int.t
val t_of_sexp : Sexplib.Sexp.t -> t
val sexp_of_t : t -> Sexplib.Sexp.t
type t_frozen = t

Type of bigstrings which support hashing. Note that mutation invalidates previous hashes.

include sig ... end
val bin_t_frozen : t_frozen Bin_prot.Type_class.t
val bin_read_t_frozen : t_frozen Bin_prot.Read.reader
val __bin_read_t_frozen__ : (Base.Int.t -> t_frozen) Bin_prot.Read.reader
val bin_reader_t_frozen : t_frozen Bin_prot.Type_class.reader
val bin_size_t_frozen : t_frozen Bin_prot.Size.sizer
val bin_write_t_frozen : t_frozen Bin_prot.Write.writer
val bin_writer_t_frozen : t_frozen Bin_prot.Type_class.writer
val bin_shape_t_frozen : Bin_prot.Shape.t
val compare_t_frozen : t_frozen -> t_frozen -> Base.Int.t
val hash_fold_t_frozen : Base.Hash.state -> t_frozen -> Base.Hash.state
val hash_t_frozen : t_frozen -> Base.Hash.hash_value
val t_frozen_of_sexp : Sexplib.Sexp.t -> t_frozen
val sexp_of_t_frozen : t_frozen -> Sexplib.Sexp.t
include Base.Equal.S with type t := t
val equal : t Base.Equal.equal
include Core_kernel.Hexdump.S with type t := t

Creation and string conversion

val create : ?max_mem_waiting_gc:Core_kernel.Byte_units.t -> Base.Int.t -> t

create length

  • parameter max_mem_waiting_gc

    default = 256 M in OCaml <= 3.12, 1 G otherwise. As the total allocation of calls to create approach max_mem_waiting_gc, the pressure in the garbage collector to be more agressive will increase.

  • returns

    a new bigstring having length. Content is undefined.

val init : Base.Int.t -> f:(Base.Int.t -> Base.Char.t) -> t

init n ~f creates a bigstring t of length n, with t.{i} = f i

val of_string : ?pos:Base.Int.t -> ?len:Base.Int.t -> Base.String.t -> t

of_string ?pos ?len str

  • returns

    a new bigstring that is equivalent to the substring of length len in str starting at position pos.

  • parameter pos

    default = 0

  • parameter len

    default = String.length str - pos

val of_bytes : ?pos:Base.Int.t -> ?len:Base.Int.t -> Base.Bytes.t -> t

of_bytes ?pos ?len str

  • returns

    a new bigstring that is equivalent to the subbytes of length len in str starting at position pos.

  • parameter pos

    default = 0

  • parameter len

    default = Bytes.length str - pos

val to_string : ?pos:Base.Int.t -> ?len:Base.Int.t -> t -> Base.String.t

to_string ?pos ?len bstr

  • returns

    a new string that is equivalent to the substring of length len in bstr starting at position pos.

  • parameter pos

    default = 0

  • parameter len

    default = length bstr - pos

  • raises Invalid_argument

    if the string would exceed runtime limits.

val to_bytes : ?pos:Base.Int.t -> ?len:Base.Int.t -> t -> Base.Bytes.t

to_bytes ?pos ?len bstr

  • returns

    a new byte sequence that is equivalent to the substring of length len in bstr starting at position pos.

  • parameter pos

    default = 0

  • parameter len

    default = length bstr - pos

  • raises Invalid_argument

    if the bytes would exceed runtime limits.

val concat : ?sep:t -> t Base.List.t -> t

concat ?sep list returns the concatenation of list with sep in between each.

Checking

val check_args : loc:Base.String.t -> pos:Base.Int.t -> len:Base.Int.t -> t -> Base.Unit.t

check_args ~loc ~pos ~len bstr checks the position and length arguments pos and len for bigstrings bstr.

  • raises

    Invalid_argument if these arguments are illegal for the given bigstring using loc to indicate the calling context.

val get_opt_len : t -> pos:Base.Int.t -> Base.Int.t Base.Option.t -> Base.Int.t

get_opt_len bstr ~pos opt_len

  • returns

    the length of a subbigstring in bstr starting at position pos and given optional length opt_len. This function does not check the validity of its arguments. Use check_args for that purpose.

Accessors

val length : t -> Base.Int.t

length bstr

  • returns

    the length of bigstring bstr.

val sub_shared : ?pos:Base.Int.t -> ?len:Base.Int.t -> t -> t

sub_shared ?pos ?len bstr

  • returns

    the sub-bigstring in bstr that starts at position pos and has length len. The sub-bigstring shares the same memory region, i.e. modifying it will modify the original bigstring. Holding on to the sub-bigstring will also keep the (usually bigger) original one around.

  • parameter pos

    default = 0

  • parameter len

    default = Bigstring.length bstr - pos

val get : t -> Base.Int.t -> Base.Char.t

get t pos returns the character at pos

val set : t -> Base.Int.t -> Base.Char.t -> Base.Unit.t

set t pos sets the character at pos

val is_mmapped : t -> Base.Bool.t

is_mmapped bstr

  • returns

    whether the bigstring bstr is memory-mapped.

Blitting

blit ~src ?src_pos ?src_len ~dst ?dst_pos () blits src_len characters from src starting at position src_pos to dst at position dst_pos.

  • raises Invalid_argument

    if the designated ranges are out of bounds.

include Core_kernel.Blit.S with type t := t
val blit : (t, t) Base.Blit_intf.blit
val blito : (t, t) Base.Blit_intf.blito
val unsafe_blit : (t, t) Base.Blit_intf.blit
val sub : (t, t) Base.Blit_intf.sub
val subo : (t, t) Base.Blit_intf.subo

Reading/writing bin-prot

These functions write the "size-prefixed" bin-prot format that is used by, e.g., async's Writer.write_bin_prot, Reader.read_bin_prot and Unpack_buffer.Unpack_one.create_bin_prot.

val write_bin_prot : t -> ?pos:Base.Int.t -> 'a Bin_prot.Type_class.writer -> 'a -> Base.Int.t

write_bin_prot t writer a writes a to t starting at pos, and returns the index in t immediately after the last byte written. It raises if pos < 0 or if a doesn't fit in t.

val read_bin_prot : t -> ?pos:Base.Int.t -> ?len:Base.Int.t -> 'a Bin_prot.Type_class.reader -> ('a * Base.Int.t) Core_kernel.Or_error.t

The read_bin_prot* functions read from the region of t starting at pos of length len. They return the index in t immediately after the last byte read. They raise if pos and len don't describe a region of t.

val read_bin_prot_verbose_errors : t -> ?pos:Base.Int.t -> ?len:Base.Int.t -> 'a Bin_prot.Type_class.reader -> [ `Invalid_data of Core_kernel.Error.t | `Not_enough_data | `Ok of 'a * Base.Int.t ]
val find : ?pos:Base.Int.t -> ?len:Base.Int.t -> Base.Char.t -> t -> Base.Int.t Base.Option.t

find ?pos ?len char t returns Some i for the smallest i >= pos such that t.{i} = char, or None if there is no such i.

  • parameter pos

    default = 0

  • parameter len

    default = length bstr - pos

val unsafe_find : t -> Base.Char.t -> pos:Base.Int.t -> len:Base.Int.t -> Base.Int.t

Same as find, but does no bounds checking, and returns a negative value instead of None if char is not found.

Destruction

val unsafe_destroy : t -> Base.Unit.t

unsafe_destroy bstr destroys the bigstring by deallocating its associated data or, if memory-mapped, unmapping the corresponding file, and setting all dimensions to zero. This effectively frees the associated memory or address-space resources instantaneously. This feature helps working around a bug in the current OCaml runtime, which does not correctly estimate how aggressively to reclaim such resources.

This operation is safe unless you have passed the bigstring to another thread that is performing operations on it at the same time. Access to the bigstring after this operation will yield array bounds exceptions.

  • raises Failure

    if the bigstring has already been deallocated (or deemed "external", which is treated equivalently), or if it has proxies, i.e. other bigstrings referring to the same data.

Accessors for parsing binary values, analogous to binary_packing

These are in Bigstring rather than a separate module because:

1) Existing binary_packing requires copies and does not work with bigstrings 2) The accessors rely on the implementation of bigstring, and hence should change should the implementation of bigstring move away from Bigarray. 3) Bigstring already has some external C functions, so it didn't require many changes to the OMakefile ^_^.

In a departure from Binary_packing, the naming conventions are chosen to be close to C99 stdint types, as it's a more standard description and it is somewhat useful in making compact macros for the implementations. The accessor names contain endian-ness to allow for branch-free implementations

<accessor> ::= <unsafe><operation><type><endian> <unsafe> ::= unsafe_ | '' <operation> ::= get_ | set_ <type> ::= int8 | uint8 | int16 | uint16 | int32 | uint32 | int64 | uint64 <endian> ::= _le | _be | ''

The "unsafe_" prefix indicates that these functions do no bounds checking.

val get_int8 : t -> pos:Base.Int.t -> Base.Int.t
val set_int8 : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val get_uint8 : t -> pos:Base.Int.t -> Base.Int.t
val set_uint8 : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val unsafe_get_int8 : t -> pos:Base.Int.t -> Base.Int.t
val unsafe_set_int8 : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val unsafe_get_uint8 : t -> pos:Base.Int.t -> Base.Int.t
val unsafe_set_uint8 : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t

16-bit methods

val get_int16_le : t -> pos:Base.Int.t -> Base.Int.t
val get_int16_be : t -> pos:Base.Int.t -> Base.Int.t
val set_int16_le : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val set_int16_be : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val unsafe_get_int16_le : t -> pos:Base.Int.t -> Base.Int.t
val unsafe_get_int16_be : t -> pos:Base.Int.t -> Base.Int.t
val unsafe_set_int16_le : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val unsafe_set_int16_be : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val get_uint16_le : t -> pos:Base.Int.t -> Base.Int.t
val get_uint16_be : t -> pos:Base.Int.t -> Base.Int.t
val set_uint16_le : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val set_uint16_be : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val unsafe_get_uint16_le : t -> pos:Base.Int.t -> Base.Int.t
val unsafe_get_uint16_be : t -> pos:Base.Int.t -> Base.Int.t
val unsafe_set_uint16_le : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val unsafe_set_uint16_be : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t

32-bit methods

val get_int32_le : t -> pos:Base.Int.t -> Base.Int.t
val get_int32_be : t -> pos:Base.Int.t -> Base.Int.t
val set_int32_le : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val set_int32_be : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val unsafe_get_int32_le : t -> pos:Base.Int.t -> Base.Int.t
val unsafe_get_int32_be : t -> pos:Base.Int.t -> Base.Int.t
val unsafe_set_int32_le : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val unsafe_set_int32_be : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val get_uint32_le : t -> pos:Base.Int.t -> Base.Int.t
val get_uint32_be : t -> pos:Base.Int.t -> Base.Int.t
val set_uint32_le : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val set_uint32_be : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val unsafe_get_uint32_le : t -> pos:Base.Int.t -> Base.Int.t
val unsafe_get_uint32_be : t -> pos:Base.Int.t -> Base.Int.t
val unsafe_set_uint32_le : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val unsafe_set_uint32_be : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t

Similar to the usage in binary_packing, the below methods are treating the value being read (or written), as an ocaml immediate integer, as such it is actually 63 bits. If the user is confident that the range of values used in practice will not require 64-bit precision (i.e. Less than Max_Long), then we can avoid allocation and use an immediate. If the user is wrong, an exception will be thrown (for get).

64-bit signed values

val get_int64_le_exn : t -> pos:Base.Int.t -> Base.Int.t
val get_int64_be_exn : t -> pos:Base.Int.t -> Base.Int.t
val get_int64_le_trunc : t -> pos:Base.Int.t -> Base.Int.t
val get_int64_be_trunc : t -> pos:Base.Int.t -> Base.Int.t
val set_int64_le : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val set_int64_be : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val unsafe_get_int64_le_exn : t -> pos:Base.Int.t -> Base.Int.t
val unsafe_get_int64_be_exn : t -> pos:Base.Int.t -> Base.Int.t
val unsafe_get_int64_le_trunc : t -> pos:Base.Int.t -> Base.Int.t
val unsafe_get_int64_be_trunc : t -> pos:Base.Int.t -> Base.Int.t
val unsafe_set_int64_le : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val unsafe_set_int64_be : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t

64-bit unsigned values

val get_uint64_be_exn : t -> pos:Base.Int.t -> Base.Int.t
val get_uint64_le_exn : t -> pos:Base.Int.t -> Base.Int.t
val set_uint64_le : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val set_uint64_be : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val unsafe_get_uint64_be_exn : t -> pos:Base.Int.t -> Base.Int.t
val unsafe_get_uint64_le_exn : t -> pos:Base.Int.t -> Base.Int.t
val unsafe_set_uint64_le : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t
val unsafe_set_uint64_be : t -> pos:Base.Int.t -> Base.Int.t -> Base.Unit.t

32-bit methods with full precision

val get_int32_t_le : t -> pos:Base.Int.t -> Core_kernel.Int32.t
val get_int32_t_be : t -> pos:Base.Int.t -> Core_kernel.Int32.t
val set_int32_t_le : t -> pos:Base.Int.t -> Core_kernel.Int32.t -> Base.Unit.t
val set_int32_t_be : t -> pos:Base.Int.t -> Core_kernel.Int32.t -> Base.Unit.t
val unsafe_get_int32_t_le : t -> pos:Base.Int.t -> Core_kernel.Int32.t
val unsafe_get_int32_t_be : t -> pos:Base.Int.t -> Core_kernel.Int32.t
val unsafe_set_int32_t_le : t -> pos:Base.Int.t -> Core_kernel.Int32.t -> Base.Unit.t
val unsafe_set_int32_t_be : t -> pos:Base.Int.t -> Core_kernel.Int32.t -> Base.Unit.t

64-bit methods with full precision

val get_int64_t_le : t -> pos:Base.Int.t -> Core_kernel.Int64.t
val get_int64_t_be : t -> pos:Base.Int.t -> Core_kernel.Int64.t
val set_int64_t_le : t -> pos:Base.Int.t -> Core_kernel.Int64.t -> Base.Unit.t
val set_int64_t_be : t -> pos:Base.Int.t -> Core_kernel.Int64.t -> Base.Unit.t
val unsafe_get_int64_t_le : t -> pos:Base.Int.t -> Core_kernel.Int64.t
val unsafe_get_int64_t_be : t -> pos:Base.Int.t -> Core_kernel.Int64.t
val unsafe_set_int64_t_le : t -> pos:Base.Int.t -> Core_kernel.Int64.t -> Base.Unit.t
val unsafe_set_int64_t_be : t -> pos:Base.Int.t -> Core_kernel.Int64.t -> Base.Unit.t
val get_tail_padded_fixed_string : padding:Base.Char.t -> t -> pos:Base.Int.t -> len:Base.Int.t -> Base.Unit.t -> Base.String.t

Similar to Binary_packing.unpack_tail_padded_fixed_string and .pack_tail_padded_fixed_string.

val set_tail_padded_fixed_string : padding:Base.Char.t -> t -> pos:Base.Int.t -> len:Base.Int.t -> Base.String.t -> Base.Unit.t
val get_head_padded_fixed_string : padding:Base.Char.t -> t -> pos:Base.Int.t -> len:Base.Int.t -> Base.Unit.t -> Base.String.t
val set_head_padded_fixed_string : padding:Base.Char.t -> t -> pos:Base.Int.t -> len:Base.Int.t -> Base.String.t -> Base.Unit.t
exception IOError of int * exn

Type of I/O errors

In IOError (n, exn), n is the number of bytes successfully read/written before the error and exn is the occured exception (e.g. Unix_error, End_of_file)

Input functions
val read : ?min_len:int -> Unix.file_descr -> ?pos:int -> ?len:int -> t -> int

read ?min_len fd ?pos ?len bstr reads at least min_len (must be greater than or equal zero) and at most len (must be greater than or equal to min_len) bytes from file descriptor fd, and writes them to bigstring bstr starting at position pos.

  • returns

    the number of bytes actually read.

    read returns zero only if len = 0. If len > 0 and there's nothing left to read, read raises to indicate EOF even if min_len = 0.

    NOTE: even if len is zero, there may still be errors when reading from the descriptor!

  • raises Invalid_argument

    if the designated ranges are out of bounds.

  • raises IOError

    in the case of input errors, or on EOF if the minimum length could not be read.

  • parameter pos

    default = 0

  • parameter min_len

    default = 0

  • parameter len

    default = length bstr - pos

val really_read : Unix.file_descr -> ?pos:int -> ?len:int -> t -> unit

really_read fd ?pos ?len bstr reads len bytes from file descriptor fd, and writes them to bigstring bstr starting at position pos.

  • raises Invalid_argument

    if the designated range is out of bounds.

  • raises IOError

    in the case of input errors, or on EOF.

  • parameter pos

    default = 0

  • parameter len

    default = length bstr - pos

val really_recv : Unix.file_descr -> ?pos:int -> ?len:int -> t -> unit

really_recv sock ?pos ?len bstr receives len bytes from socket sock, and writes them to bigstring bstr starting at position pos. If len is zero, the function returns immediately without performing the underlying system call.

  • raises Invalid_argument

    if the designated range is out of bounds.

  • raises IOError

    in the case of input errors, or on EOF.

  • parameter pos

    default = 0

  • parameter len

    default = length bstr - pos

val recvfrom_assume_fd_is_nonblocking : Unix.file_descr -> ?pos:int -> ?len:int -> t -> int * Unix.sockaddr

recvfrom_assume_fd_is_nonblocking sock ?pos ?len bstr reads up to len bytes into bigstring bstr starting at position pos from socket sock without yielding to other OCaml-threads.

  • returns

    the number of bytes actually read and the socket address of the client.

  • raises Unix_error

    in the case of input errors.

  • raises Invalid_argument

    if the designated range is out of bounds.

  • parameter pos

    default = 0

  • parameter len

    default = length bstr - pos

val read_assume_fd_is_nonblocking : Unix.file_descr -> ?pos:int -> ?len:int -> t -> int

read_assume_fd_is_nonblocking fd ?pos ?len bstr reads up to len bytes into bigstring bstr starting at position pos from file descriptor fd without yielding to other OCaml-threads.

  • returns

    the number of bytes actually read.

  • raises Invalid_argument

    if the designated range is out of bounds.

  • parameter pos

    default = 0

  • parameter len

    default = length bstr - pos

val pread_assume_fd_is_nonblocking : Unix.file_descr -> offset:int -> ?pos:int -> ?len:int -> t -> int

pread_assume_fd_is_nonblocking fd ~offset ?pos ?len bstr reads up to len bytes from file descriptor fd at offset offset, and writes them to bigstring bstr starting at position pos. The fd must be capable of seeking, and the current file offset used for a regular read() is unchanged. Please see 'man pread' for more information.

  • returns

    the number of bytes actually read.

  • raises Invalid_argument

    if the designated range is out of bounds.

  • raises Unix_error

    in the case of input errors.

  • parameter pos

    default = 0

  • parameter len

    default = length bstr - pos

val input : ?min_len:int -> Core_kernel.In_channel.t -> ?pos:int -> ?len:int -> t -> int

input ?min_len ic ?pos ?len bstr tries to read len bytes (guarantees to read at least min_len bytes (must be greater than or equal to zero and smaller or equal to len), if possible, before returning) from input channel ic, and writes them to bigstring bstr starting at position pos.

  • returns

    the number of bytes actually read.

    NOTE: even if len is zero, there may still be errors when reading from the descriptor, which will be done if the internal buffer is empty!

    NOTE: if at least len characters are available in the input channel buffer and if len is not zero, data will only be fetched from the channel buffer. Otherwise data will be read until at least min_len characters are available.

  • raises Invalid_argument

    if the designated range is out of bounds.

  • raises IOError

    in the case of input errors, or on premature EOF.

  • parameter pos

    default = 0

  • parameter min_len

    default = 0

  • parameter len

    default = length bstr - pos

val really_input : Core_kernel.In_channel.t -> ?pos:int -> ?len:int -> t -> unit

really_input ic ?pos ?len bstr reads exactly len bytes from input channel ic, and writes them to bigstring bstr starting at position pos.

  • raises Invalid_argument

    if the designated range is out of bounds.

  • raises IOError

    in the case of input errors, or on premature EOF.

  • parameter pos

    default = 0

  • parameter len

    default = length bstr - pos

Output functions
val really_write : Unix.file_descr -> ?pos:int -> ?len:int -> t -> unit

really_write fd ?pos ?len bstr writes len bytes in bigstring bstr starting at position pos to file descriptor fd.

  • raises Invalid_argument

    if the designated range is out of bounds.

  • raises IOError

    in the case of output errors.

  • parameter pos

    default = 0

  • parameter len

    default = length bstr - pos

val really_send_no_sigpipe : (Unix.file_descr -> ?pos:int -> ?len:int -> t -> unit) Core_kernel.Or_error.t

really_send_no_sigpipe sock ?pos ?len bstr sends len bytes in bigstring bstr starting at position pos to socket sock without blocking and ignoring SIGPIPE.

  • raises Invalid_argument

    if the designated range is out of bounds.

  • raises IOError

    in the case of output errors.

  • parameter pos

    default = 0

  • parameter len

    default = length bstr - pos

    really_send_no_sigpipe is not implemented on some platforms, in which case it is an Error value that indicates that it is unimplemented.

val send_nonblocking_no_sigpipe : (Unix.file_descr -> ?pos:int -> ?len:int -> t -> int) Core_kernel.Or_error.t

send_nonblocking_no_sigpipe sock ?pos ?len bstr tries to send len bytes in bigstring bstr starting at position pos to socket sock.

  • returns

    bytes_written.

  • raises Invalid_argument

    if the designated range is out of bounds.

  • parameter pos

    default = 0

  • parameter len

    default = length bstr - pos

val sendto_nonblocking_no_sigpipe : (Unix.file_descr -> ?pos:int -> ?len:int -> t -> Unix.sockaddr -> int) Core_kernel.Or_error.t

sendto_nonblocking_no_sigpipe sock ?pos ?len bstr sockaddr tries to send len bytes in bigstring bstr starting at position pos to socket sock using address addr.

  • returns

    bytes_written.

  • raises Invalid_argument

    if the designated range is out of bounds.

  • parameter pos

    default = 0

  • parameter len

    default = length bstr - pos

val write : Unix.file_descr -> ?pos:int -> ?len:int -> t -> int

write fd ?pos ?len bstr writes len bytes in bigstring bstr starting at position pos to file descriptor fd.

  • returns

    the number of bytes actually written.

  • raises Unix_error

    in the case of output errors.

  • raises Invalid_argument

    if the designated range is out of bounds.

  • parameter pos

    default = 0

  • parameter len

    default = length bstr - pos

val pwrite_assume_fd_is_nonblocking : Unix.file_descr -> offset:int -> ?pos:int -> ?len:int -> t -> int

pwrite_assume_fd_is_nonblocking fd ~offset ?pos ?len bstr writes up to len bytes of bigstring bstr starting at position pos to file descriptor fd at position offset. The fd must be capable of seeking, and the current file offset used for non-positional read()/write() calls is unchanged.

  • returns

    the number of bytes written.

  • raises Invalid_argument

    if the designated range is out of bounds.

  • raises Unix_error

    in the case of input errors.

  • parameter pos

    default = 0

  • parameter len

    default = length bstr - pos

val write_assume_fd_is_nonblocking : Unix.file_descr -> ?pos:int -> ?len:int -> t -> int

write_assume_fd_is_nonblocking fd ?pos ?len bstr writes len bytes in bigstring bstr starting at position pos to file descriptor fd without yielding to other OCaml-threads.

  • returns

    the number of bytes actually written.

  • raises Unix_error

    in the case of output errors.

  • raises Invalid_argument

    if the designated range is out of bounds.

  • parameter pos

    default = 0

  • parameter len

    default = length bstr - pos

val writev : Unix.file_descr -> ?count:int -> t Core__.Core_unix.IOVec.t array -> int

writev fd ?count iovecs writes count iovecs of bigstrings to file descriptor fd.

  • returns

    the number of bytes written.

  • raises Unix_error

    in the case of output errors.

  • raises Invalid_argument

    if count is out of range.

  • parameter count

    default = Array.length iovecs

val writev_assume_fd_is_nonblocking : Unix.file_descr -> ?count:int -> t Core__.Core_unix.IOVec.t array -> int

writev_assume_fd_is_nonblocking fd ?count iovecs writes count iovecs of bigstrings to file descriptor fd without yielding to other OCaml-threads.

  • returns

    the number of bytes actually written.

  • raises Unix_error

    in the case of output errors.

  • raises Invalid_argument

    if the designated range is out of bounds.

  • parameter count

    default = Array.length iovecs

val recvmmsg_assume_fd_is_nonblocking : (Unix.file_descr -> ?count:int -> ?srcs:Unix.sockaddr array -> t Core__.Core_unix.IOVec.t array -> lens:int array -> int) Core_kernel.Or_error.t

recvmmsg_assume_fd_is_nonblocking fd iovecs ~count ~lens receives up to count messages into iovecs from file descriptor fd without yielding to other OCaml threads. If ~count is supplied, it must be that 0 <= count <= Array.length iovecs. If ~srcs is supplied, save the source addresses for corresponding received messages there. If supplied, Array.length srcs must be >= count. Save the lengths of the received messages in lens. It is required that Array.length lens >= count.

If an IOVec isn't long enough for its corresponding message, excess bytes may be discarded, depending on the type of socket the message is received from. While the recvmmsg system call itself does return details of such truncation, etc., those details are not (yet) passed through this interface.

  • see recvmmsg(2)

    re. the underlying system call.

  • returns

    the number of messages actually read, or a negative number to indicate EWOULDBLOCK or EAGAIN. This is a compromise to mitigate the exception overhead for what ends up being a very common result with our use of recvmmsg.

  • raises Unix_error

    in the case of output errors.

  • raises Invalid_argument

    if the designated range is out of bounds.

  • parameter count

    default = Array.length iovecs

val sendmsg_nonblocking_no_sigpipe : (Unix.file_descr -> ?count:int -> t Core__.Core_unix.IOVec.t array -> int option) Core_kernel.Or_error.t

sendmsg_nonblocking_no_sigpipe sock ?count iovecs sends count iovecs of bigstrings to socket sock.

  • returns

    Some bytes_written, or None if the operation would have blocked. This system call will not cause signal SIGPIPE if an attempt is made to write to a socket that was closed by the other side.

  • raises Unix_error

    in the case of output errors.

  • raises Invalid_argument

    if count is out of range.

  • parameter count

    default = Array.length iovecs

val output : ?min_len:int -> Core_kernel.Out_channel.t -> ?pos:int -> ?len:int -> t -> int

output ?min_len oc ?pos ?len bstr tries to output len bytes (guarantees to write at least min_len bytes (must be equal to or greater than zero), if possible, before returning) from bigstring bstr starting at position pos to output channel oc.

  • returns

    the number of bytes actually written.

    NOTE: you may need to flush oc to make sure that the data is actually sent.

    NOTE: if len characters fit into the channel buffer completely, they will be buffered. Otherwise writes will be attempted until at least min_len characters have been sent.

  • raises Invalid_argument

    if the designated range is out of bounds.

  • raises IOError

    in the case of output errors. The IOError-argument counting the number of successful bytes includes those that have been transferred to the channel buffer before the error.

  • parameter pos

    default = 0

  • parameter min_len

    default = 0

  • parameter len

    default = length bstr - pos

val really_output : Core_kernel.Out_channel.t -> ?pos:int -> ?len:int -> t -> unit

really_output oc ?pos ?len bstr outputs exactly len bytes from bigstring bstr starting at position pos to output channel oc.

  • raises Invalid_argument

    if the designated range is out of bounds.

  • raises IOError

    in the case of output errors. The IOError-argument counting the number of successful bytes includes those that have been transferred to the channel buffer before the error.

  • parameter pos

    default = 0

  • parameter len

    default = length bstr - pos

Unsafe functions
val unsafe_read_assume_fd_is_nonblocking : Unix.file_descr -> pos:int -> len:int -> t -> int

unsafe_read_assume_fd_is_nonblocking fd ~pos ~len bstr similar to Bigstring.read_assume_fd_is_nonblocking, but does not perform any bounds checks. Will crash on bounds errors!

val unsafe_write : Unix.file_descr -> pos:int -> len:int -> t -> int

unsafe_write fd ~pos ~len bstr similar to Bigstring.write, but does not perform any bounds checks. Will crash on bounds errors!

val unsafe_write_assume_fd_is_nonblocking : Unix.file_descr -> pos:int -> len:int -> t -> int

unsafe_write_assume_fd_is_nonblocking fd ~pos ~len bstr similar to Bigstring.write_assume_fd_is_nonblocking, but does not perform any bounds checks. Will crash on bounds errors!

val unsafe_read : min_len:int -> Unix.file_descr -> pos:int -> len:int -> t -> int

unsafe_read ~min_len fd ~pos ~len bstr similar to Bigstring.read, but does not perform any bounds checks. Will crash on bounds errors!

val unsafe_really_recv : Unix.file_descr -> pos:int -> len:int -> t -> unit

unsafe_really_recv sock ~pos ~len bstr similar to Bigstring.really_recv, but does not perform any bounds checks. Will crash on bounds errors!

val unsafe_really_write : Unix.file_descr -> pos:int -> len:int -> t -> unit

unsafe_really_write fd ~pos ~len bstr similar to Bigstring.write, but does not perform any bounds checks. Will crash on bounds errors!

val unsafe_really_send_no_sigpipe : (Unix.file_descr -> pos:int -> len:int -> t -> unit) Core_kernel.Or_error.t

unsafe_really_send_no_sigpipe sock ~pos ~len bstr similar to Bigstring.send, but does not perform any bounds checks. Will crash on bounds errors!

val unsafe_send_nonblocking_no_sigpipe : (Unix.file_descr -> pos:int -> len:int -> t -> int) Core_kernel.Or_error.t

unsafe_send_nonblocking_no_sigpipe sock ~pos ~len bstr similar to Bigstring.send_nonblocking_no_sigpipe, but does not perform any bounds checks. Will crash on bounds errors!

val unsafe_writev : Unix.file_descr -> t Core__.Core_unix.IOVec.t array -> int -> int

unsafe_writev fd iovecs count similar to Bigstring.writev, but does not perform any bounds checks. Will crash on bounds errors!

val unsafe_sendmsg_nonblocking_no_sigpipe : (Unix.file_descr -> t Core__.Core_unix.IOVec.t array -> int -> int option) Core_kernel.Or_error.t

unsafe_sendmsg_nonblocking_no_sigpipe fd iovecs count similar to Bigstring.sendmsg_nonblocking_no_sigpipe, but does not perform any bounds checks. Will crash on bounds errors!

val unsafe_input : min_len:int -> Core_kernel.In_channel.t -> pos:int -> len:int -> t -> int

unsafe_input ~min_len ic ~pos ~len bstr similar to Bigstring.input, but does not perform any bounds checks. Will crash on bounds errors!

val unsafe_output : min_len:int -> Core_kernel.Out_channel.t -> pos:int -> len:int -> t -> int

unsafe_output ~min_len oc ~pos ~len bstr similar to Bigstring.output, but does not perform any bounds checks. Will crash on bounds errors!

Memory mapping
val map_file : shared:bool -> Unix.file_descr -> int -> t

map_file shared fd n memory-maps n characters of the data associated with descriptor fd to a bigstring. Iff shared is true, all changes to the bigstring will be reflected in the file.

Users must keep in mind that operations on the resulting bigstring may result in disk operations which block the runtime. This is true for pure OCaml operations (such as t.

<- 1), and for calls to blit. While some I/O operations may release the OCaml lock, users should not expect this to be done for all operations on a bigstring returned from map_file.

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct