package core_unix
Install
Dune Dependency
Authors
Maintainers
Sources
md5=9370dca36f518fcea046d2752e3de22b
sha512=c4e8ce9d5885ac8fa8d554a97e1857f3a1c933e0eb5dfd4fe874412b9d09e6d0a2973b644733855553f33f5c859719228f0e6aaf3a2b7eb5befb46fc513750de
doc/core_unix.bigstring_unix/Bigstring_unix/index.html
Module Bigstring_unixSource
String type based on Bigarray, for use in I/O and C-bindings, extending Core.Bigstring.
module Unix := Core_unixinclude module type of struct include Core.Bigstring end
Types and exceptions
Type of bigstrings
include Ppx_compare_lib.Comparable.S with type t := t
include Ppx_quickcheck_runtime.Quickcheckable.S with type t := t
Type of bigstrings which support hashing. Note that mutation invalidates previous hashes.
include module type of Base_bigstring
with type t := t
and type t_frozen := t_frozen
Types and exceptions
include Ppx_compare_lib.Comparable.S with type t := t
include Sexplib0.Sexpable.S with type t := t
val t_of_sexp : Sexplib0.Sexp.t -> tval sexp_of_t : t -> Sexplib0.Sexp.tval hash_fold_t_frozen :
Ppx_hash_lib.Std.Hash.state ->
t_frozen ->
Ppx_hash_lib.Std.Hash.stateval hash_t_frozen : t_frozen -> Ppx_hash_lib.Std.Hash.hash_valueval sexp_of_t_frozen : t_frozen -> Sexplib0.Sexp.tval t_frozen_of_sexp : Sexplib0.Sexp.t -> t_frozeninclude Base.Equal.S with type t := t
val equal : t Base.Equal.equalCreation and string conversion
init n ~f creates a bigstring t of length n, with t.{i} = f i.
val of_string : ?pos:Base.int -> ?len:Base.int -> Base.string -> tof_string ?pos ?len str
val of_bytes : ?pos:Base.int -> ?len:Base.int -> Base.bytes -> tof_bytes ?pos ?len str
val to_string : ?pos:Base.int -> ?len:Base.int -> t -> Base.stringto_string ?pos ?len bstr
val to_bytes : ?pos:Base.int -> ?len:Base.int -> t -> Base.bytesto_bytes ?pos ?len bstr
concat ?sep list returns the concatenation of list with sep in between each.
Checking
val check_args :
loc:Base.string ->
pos:Base.int ->
len:Base.int ->
t ->
Base.unitcheck_args ~loc ~pos ~len bstr checks the position and length arguments pos and len for bigstrings bstr.
val get_opt_len : t -> pos:Base.int -> Base.int Base.option -> Base.intget_opt_len bstr ~pos opt_len
Accessors
unsafe_get t pos returns the character at pos, without bounds checks.
unsafe_set t pos sets the character at pos, without bounds checks.
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.
include Base.Blit.S with type t := t
module To_string = Core.Bigstring.To_stringmodule From_string = Core.Bigstring.From_stringmodule To_bytes = Core.Bigstring.To_bytesmodule From_bytes = Core.Bigstring.From_bytesmemset t ~pos ~len c fills t with c within the range [pos, pos + len).
unsafe_memset t ~pos ~len c fills t with c within the range [pos, pos + len), without bounds checks.
Memcmp
memcmp t1 ~pos1 t2 ~pos2 ~len is like compare t1 t2 except performs the comparison on the subregions of t1 and t2 defined by pos1, pos2, and len.
memcmp_bytes, for efficient memcmp between Bigstring and Bytes data.
memcmp_string, for efficient memcmp between Bigstring and string data.
Search
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.
Same as find, but does no bounds checking, and returns a negative value instead of None if char is not found.
val memmem :
haystack:t ->
needle:t ->
?haystack_pos:Base.int ->
?haystack_len:Base.int ->
?needle_pos:Base.int ->
?needle_len:Base.int ->
Base.unit ->
Base.int Base.optionSearch for the position of (a substring of) needle in (a substring of) haystack.
val unsafe_memmem :
haystack:t ->
needle:t ->
haystack_pos:Base.int ->
haystack_len:Base.int ->
needle_pos:Base.int ->
needle_len:Base.int ->
Base.intAs unsafe_find for memmem.
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 jbuild ^_^.
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 and silently truncate out-of-range numeric arguments.
16-bit methods
32-bit methods
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
64-bit unsigned values
32-bit methods with full precision
val get_int32_t_le : t -> pos:Base.int -> Base.Int32.tval get_int32_t_be : t -> pos:Base.int -> Base.Int32.tval set_int32_t_le : t -> pos:Base.int -> Base.Int32.t -> Base.unitval set_int32_t_be : t -> pos:Base.int -> Base.Int32.t -> Base.unitval unsafe_get_int32_t_le : t -> pos:Base.int -> Base.Int32.tval unsafe_get_int32_t_be : t -> pos:Base.int -> Base.Int32.tval unsafe_set_int32_t_le : t -> pos:Base.int -> Base.Int32.t -> Base.unitval unsafe_set_int32_t_be : t -> pos:Base.int -> Base.Int32.t -> Base.unit64-bit methods with full precision
val get_int64_t_le : t -> pos:Base.int -> Base.Int64.tval get_int64_t_be : t -> pos:Base.int -> Base.Int64.tval set_int64_t_le : t -> pos:Base.int -> Base.Int64.t -> Base.unitval set_int64_t_be : t -> pos:Base.int -> Base.Int64.t -> Base.unitval unsafe_get_int64_t_le : t -> pos:Base.int -> Base.Int64.tval unsafe_get_int64_t_be : t -> pos:Base.int -> Base.Int64.tval unsafe_set_int64_t_le : t -> pos:Base.int -> Base.Int64.t -> Base.unitval unsafe_set_int64_t_be : t -> pos:Base.int -> Base.Int64.t -> Base.unitString methods
These are alternatives to to_string that follow the conventions of the int accessors, and in particular avoid optional arguments.
val get_string : t -> pos:Base.int -> len:Base.int -> Base.stringval unsafe_get_string : t -> pos:Base.int -> len:Base.int -> Base.stringmodule Local = Core.Bigstring.Localmodule Int_repr = Core.Bigstring.Int_reprmodule Private = Core.Bigstring.Privateinclude Core.Hexdump.S with type t := t
Creation and string conversion
create length
sub_shared ?pos ?len bstr
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.twrite_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 write_bin_prot_known_size :
t ->
?pos:Base.Int.t ->
'a Bin_prot.Write.writer ->
size:Base.Int.t ->
'a ->
Base.Int.tSame as write_bin_prot, with the difference that size is pre-computed by the caller. size is assumed to be the result of calling the bin prot sizer on the value being written.
val read_bin_prot :
t ->
?pos:Base.Int.t ->
?len:Base.Int.t ->
'a Bin_prot.Type_class.reader ->
('a * Base.Int.t) Core.Or_error.tThe 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.Error.t | `Not_enough_data | `Ok of 'a * Base.Int.t ]Destruction
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 reclaim the resources sooner than they are automatically reclaimed by the GC.
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.
unsafe_destroy_and_resize bstr ~len reallocates the memory backing bstr and returns a new bigstring that starts at position 0 and has length len. If len is greater than length bstr then the newly allocated memory will not be initialized.
Similar to unsafe_destroy, 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 bstr after this operation will yield array bounds exceptions.
val get_tail_padded_fixed_string :
padding:Base.Char.t ->
t ->
pos:Base.Int.t ->
len:Base.Int.t ->
Base.Unit.t ->
Base.String.tSimilar to Binary_packing.unpack_tail_padded_fixed_string and .pack_tail_padded_fixed_string.
val get_tail_padded_fixed_string_local :
padding:Base.Char.t ->
t ->
pos:Base.Int.t ->
len:Base.Int.t ->
Base.Unit.t ->
Base.String.tval set_tail_padded_fixed_string :
padding:Base.Char.t ->
t ->
pos:Base.Int.t ->
len:Base.Int.t ->
Base.String.t ->
Base.Unit.tval get_head_padded_fixed_string :
padding:Base.Char.t ->
t ->
pos:Base.Int.t ->
len:Base.Int.t ->
Base.Unit.t ->
Base.String.tval get_head_padded_fixed_string_local :
padding:Base.Char.t ->
t ->
pos:Base.Int.t ->
len:Base.Int.t ->
Base.Unit.t ->
Base.String.tval set_head_padded_fixed_string :
padding:Base.Char.t ->
t ->
pos:Base.Int.t ->
len:Base.Int.t ->
Base.String.t ->
Base.Unit.tType of I/O errors.
In IOError (n, exn), n is the number of bytes successfully read/written before the error and exn is the exception that occurred (e.g., Unix_error, End_of_file)
Input functions
read ?min_len fd ?pos ?len bstr reads at least min_len (must be >= 0) and at most len (must be >= 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.
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.
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.
recv_peek_assume_fd_is_nonblocking sock ?pos ~len bstr peeks 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 Unix_error in the case of input errors
val recvfrom_assume_fd_is_nonblocking :
Unix.File_descr.t ->
?pos:int ->
?len:int ->
t ->
int * Unix.sockaddrrecvfrom_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.
val read_assume_fd_is_nonblocking :
Unix.File_descr.t ->
?pos:int ->
?len:int ->
t ->
Unix.Syscall_result.Int.tread_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.
val pread :
?min_len:int ->
Unix.File_descr.t ->
offset:int ->
?pos:int ->
?len:int ->
t ->
intLike read but uses pread to read from the given offset in the file.
Like really_read but uses pread to read from the given offset in the file.
val pread_assume_fd_is_nonblocking :
Unix.File_descr.t ->
offset:int ->
?pos:int ->
?len:int ->
t ->
intpread_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.
input ?min_len ic ?pos ?len bstr tries to read len bytes (guarantees to read at least min_len bytes, which must be >= 0 and <= 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.
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.
Output functions
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.
val really_send_no_sigpipe :
(Unix.File_descr.t -> ?pos:int -> ?len:int -> t -> unit) Core.Or_error.treally_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.
really_send_no_sigpipe is not implemented on some platforms, in which case it returns an Error value indicating that it is unimplemented.
val send_nonblocking_no_sigpipe :
(Unix.File_descr.t ->
?pos:int ->
?len:int ->
t ->
Unix.Syscall_result.Int.t)
Core.Or_error.tsend_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.
val sendto_nonblocking_no_sigpipe :
(Unix.File_descr.t ->
?pos:int ->
?len:int ->
t ->
Unix.sockaddr ->
Unix.Syscall_result.Int.t)
Core.Or_error.tsendto_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.
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 Invalid_argument if the designated range is out of bounds. Raises Unix_error in the case of output errors.
val pwrite_assume_fd_is_nonblocking :
Unix.File_descr.t ->
offset:int ->
?pos:int ->
?len:int ->
t ->
intpwrite_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 output errors.
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 Invalid_argument if the designated range is out of bounds. Raises Unix_error in the case of output errors.
writev fd ?count iovecs writes count iovecs of bigstrings to file descriptor fd. Returns the number of bytes written.
Raises Invalid_argument if count is out of range. Raises Unix_error in the case of output errors.
val writev_assume_fd_is_nonblocking :
Unix.File_descr.t ->
?count:int ->
t Unix.IOVec.t array ->
intwritev_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 Invalid_argument if the designated range is out of bounds. Raises Unix_error in the case of output errors.
val recvmmsg_assume_fd_is_nonblocking :
(Unix.File_descr.t ->
?count:int ->
?srcs:Unix.sockaddr array ->
t Unix.IOVec.t array ->
lens:int array ->
int)
Core.Or_error.trecvmmsg_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, saves the source addresses for corresponding received messages there. If supplied, Array.length srcs must be >= count. Saves 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 Invalid_argument if the designated range is out of bounds. Raises Unix_error in the case of output errors.
val unsafe_recvmmsg_assume_fd_is_nonblocking :
(Unix.File_descr.t ->
t Unix.IOVec.t array ->
int ->
Unix.sockaddr array option ->
int array ->
int)
Core.Or_error.tval sendmsg_nonblocking_no_sigpipe :
(Unix.File_descr.t ->
?count:int ->
t Unix.IOVec.t array ->
int option)
Core.Or_error.tsendmsg_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 Invalid_argument if count is out of range. Raises Unix_error in the case of output errors.
output ?min_len oc ?pos ?len bstr tries to output len bytes (guarantees to write at least min_len bytes, which must be >= 0), 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.
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.
Unsafe functions
val unsafe_read_assume_fd_is_nonblocking :
Unix.File_descr.t ->
pos:int ->
len:int ->
t ->
Unix.Syscall_result.Int.tunsafe_read_assume_fd_is_nonblocking fd ~pos ~len bstr is similar to Bigstring.read_assume_fd_is_nonblocking, but does not perform any bounds checks. Will crash on bounds errors!
unsafe_write fd ~pos ~len bstr is 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.t ->
pos:int ->
len:int ->
t ->
intunsafe_write_assume_fd_is_nonblocking fd ~pos ~len bstr is similar to Bigstring.write_assume_fd_is_nonblocking, but does not perform any bounds checks. Will crash on bounds errors!
unsafe_read ~min_len fd ~pos ~len bstr is similar to Bigstring.read, but does not perform any bounds checks. Will crash on bounds errors!
unsafe_really_recv sock ~pos ~len bstr is similar to Bigstring.really_recv, but does not perform any bounds checks. Will crash on bounds errors!
unsafe_really_write fd ~pos ~len bstr is 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.t -> pos:int -> len:int -> t -> unit) Core.Or_error.tunsafe_really_send_no_sigpipe sock ~pos ~len bstr is 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.t ->
pos:int ->
len:int ->
t ->
Unix.Syscall_result.Int.t)
Core.Or_error.tunsafe_send_nonblocking_no_sigpipe sock ~pos ~len bstr is similar to Bigstring.send_nonblocking_no_sigpipe, but does not perform any bounds checks. Will crash on bounds errors!
unsafe_writev fd iovecs count is 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 ->
t Unix.IOVec.t array ->
int ->
int option)
Core.Or_error.tunsafe_sendmsg_nonblocking_no_sigpipe fd iovecs count is similar to Bigstring.sendmsg_nonblocking_no_sigpipe, but does not perform any bounds checks. Will crash on bounds errors!
unsafe_input ~min_len ic ~pos ~len bstr is similar to Bigstring.input, but does not perform any bounds checks. Will crash on bounds errors!
unsafe_output ~min_len oc ~pos ~len bstr is similar to Bigstring.output, but does not perform any bounds checks. Will crash on bounds errors!
Memory mapping
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} <- 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.