# Module Bigstring

    module Bigstring: sig .. end

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

    include Core_kernel.Std.Bigstring

    exception IOError of int * exn

Type of I/O errors

The occurred 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`.
Raises

- `Invalid_argument` if the designated ranges are out of bounds.
- `IOError` in the case of input errors, or on EOF if the minimum length could not be read.

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!

`min_len` : default = 0
`pos` : default = 0
`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.
- `IOError` in the case of input errors, or on EOF.

`pos` : default = 0
`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.
- `IOError` in the case of input errors, or on EOF.

`pos` : default = 0
`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.
Raises

- `Unix_error` in the case of input errors.
- `Invalid_argument` if the designated range is out of bounds.

Returns the number of bytes actually read and the socket address of the client.
`pos` : default = 0
`len` : default = `length bstr - pos`

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

`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.
Raises `Invalid_argument` if the designated range is out of bounds.
Returns the number of bytes actually read.
`pos` : default = 0
`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.
Raises

- `Invalid_argument` if the designated range is out of bounds.
- `Unix_error` in the case of input errors.

Returns the number of bytes actually read.
`pos` : default = 0
`len` : default = `length bstr - pos`

    val input : ?min_len:int -> Pervasives.in_channel -> ?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`.
Raises

- `Invalid_argument` if the designated range is out of bounds.
- `IOError` in the case of input errors, or on premature EOF.

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.

`min_len` : default = 0
`pos` : default = 0
`len` : default = `length bstr - pos`

    val really_input : Pervasives.in_channel -> ?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.
- `IOError` in the case of input errors, or on premature EOF.

`pos` : default = 0
`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.
- `IOError` in the case of output errors.

`pos` : default = 0
`len` : default = `length bstr - pos`

    val really_send_no_sigpipe : (Unix.file_descr -> ?pos:int -> ?len:int -> t -> unit)
           Core_kernel.Std.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.
- `IOError` in the case of output errors.

    val send_nonblocking_no_sigpipe : (Unix.file_descr -> ?pos:int -> ?len:int -> t -> Syscall_result.Int.t)
           Core_kernel.Std.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`.
Raises `Invalid_argument` if the designated range is out of bounds.
Returns `bytes_written`.

    val sendto_nonblocking_no_sigpipe : (Unix.file_descr ->
            ?pos:int -> ?len:int -> t -> Unix.sockaddr -> Syscall_result.Int.t)
           Core_kernel.Std.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`.
Raises `Invalid_argument` if the designated range is out of bounds.
Returns `bytes_written`.

    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`.
Raises

- `Unix_error` in the case of output errors.
- `Invalid_argument` if the designated range is out of bounds.

Returns the number of bytes actually written.
`pos` : default = 0
`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.
Raises

- `Invalid_argument` if the designated range is out of bounds.
- `Unix_error` in the case of input errors.

Returns the number of bytes written.
`pos` : default = 0
`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.
Raises

- `Unix_error` in the case of output errors.
- `Invalid_argument` if the designated range is out of bounds.

Returns the number of bytes actually written.
`pos` : default = 0
`len` : default = `length bstr - pos`

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

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

- `Unix_error` in the case of output errors.
- `Invalid_argument` if count is out of range.

Returns the number of bytes written.
`count` : default = `Array.length iovecs`

    val writev_assume_fd_is_nonblocking : Unix.file_descr -> ?count:int -> t 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.
Raises

- `Unix_error` in the case of output errors.
- `Invalid_argument` if the designated range is out of bounds.

Returns the number of bytes actually written.
`count` : default = `Array.length iovecs`

    val recvmmsg_assume_fd_is_nonblocking : (Unix.file_descr ->
            ?count:int ->
            ?srcs:Unix.sockaddr array ->
            t Core_unix.IOVec.t array -> lens:int array -> int)
           Core_kernel.Std.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 recieved 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.
Raises

- `Unix_error` in the case of output errors.
- `Invalid_argument` if the designated range is out of bounds.

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`.
See also recvmmsg(2) re. the underlying system call.

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

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

- `Unix_error` in the case of output errors.
- `Invalid_argument` if `count` is out of range.

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.

    val output : ?min_len:int -> Pervasives.out_channel -> ?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`.
Raises

- `Invalid_argument` if the designated range is out of bounds.
- `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.

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.

`min_len` : default = 0
`pos` : default = 0
`len` : default = `length bstr - pos`

    val really_output : Pervasives.out_channel -> ?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.
- `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.

`pos` : default = 0
`len` : default = `length bstr - pos`

###### Unsafe functions

    val unsafe_read_assume_fd_is_nonblocking : Unix.file_descr -> pos:int -> len:int -> t -> Syscall_result.Int.t

`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.Std.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 -> Syscall_result.Int.t)
           Core_kernel.Std.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_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_unix.IOVec.t array -> int -> int option)
           Core_kernel.Std.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 -> Pervasives.in_channel -> 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 -> Pervasives.out_channel -> 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!