create ~len creates a new iobuf, backed by a bigstring of length len, with the limits and window set to the entire bigstring.

of_bigstring bigstring ~pos ~len returns an iobuf backed by bigstring, with the window and limits specified starting at pos and of length len.

of_string s returns a new iobuf whose contents are s.

sub t ~pos ~len returns a new iobuf with limits and window set to the subrange of t specified by pos and len. sub preserves data permissions, but allows arbitrary seek permissions on the resulting iobuf.

set_bounds_and_buffer ~src ~dst copies bounds (ie limits + window) and shallowly copies the buffer from src to dst. read_write access is required on src because the caller might have read_write access to dst, and would after the call then effectively have read_write access to src.

set_bounds_and_buffer_sub ?pos ?len ~src ~dst () is a more efficient version of: set_bounds_and_buffer ~src:(Iobuf.sub ?pos ?len src) ~dst.

set_bounds_and_buffer ~src ~dst is not the same as set_bounds_and_buffer_sub ~dst ~src (), because the limits are narrowed in the latter case.

One may wonder why you'd want to call read_only or no_seek, given that the casts are already possible, e.g. t : (read_write, _) t :> (read_only, _) t. It turns out that if you want to define some f : (_, seek) t -> unit of your own, which can be conveniently applied to read_only and read_write iobufs without the user having to cast read_write up, you need this read_only function.

capacity t returns the size of t's limits subrange. The capacity of an iobuf can be reduced via narrow.

length t returns the size of t's window.

is_empty t is length t = 0.

narrow t sets t's limits to the current window.

advance t amount advances the lower bound of the window by amount. It is an error to advance past the upper bound of the window or the lower limit.

unsafe_advance is like advance but with no bounds checking, so incorrect usage can easily cause segfaults.

resize t sets the length of t's window, provided it does not exceed limits.

unsafe_resize is like resize but with no bounds checking, so incorrect usage can easily cause segfaults.

rewind t sets the lower bound of the window to the lower limit.

reset t sets the window to the limits.

flip_lo t sets the window to range from the lower limit to the lower bound of the old window. This is typically called after a series of Fills, to reposition the window in preparation to Consume the newly written data.

The bounded version narrows the effective limit. This can preserve some data near the limit, such as an hypothetical packet header, in the case of bounded_flip_lo or unfilled suffix of a buffer, in bounded_flip_hi.

compact t copies data from the window to the lower limit of the iobuf and sets the window to range from the end of the copied data to the upper limit. This is typically called after a series of Consumes to save unread data and prepare for the next series of Fills and flip_lo.

flip_hi t sets the window to range from the the upper bound of the current window to the upper limit. This operation is dual to flip_lo and is typically called when the data in the current (narrowed) window has been processed and the window needs to be positioned over the remaining data in the buffer. For example:

      (* ... determine initial_data_len ... *)
      Iobuf.resize buf ~len:initial_data_len;
      (* ... and process initial data ... *)
      Iobuf.flip_hi buf;

Now the window of buf ranges over the remainder of the data.

protect_window_and_bounds t ~f applies f to t and restores t's bounds afterwards.

to_string t returns the bytes in t as a string. It does not alter the window.

to_string_hum t produces a readable, multi-line representation of an iobuf. bounds defaults to `Limits and determines how much of the contents are shown.

fill_bin_prot writes a bin-prot value to the lower bound of the window, prefixed by its length, and advances by the amount written. fill_bin_prot returns an error if the window is too small to write the value.

consume_bin_prot t reader reads a bin-prot value from the lower bound of the window, which should have been written using fill_bin_prot, and advances the window by the amount read. consume_bin_prot returns an error if there is not a complete message in the window and in that case the window is left unchanged.

Don't use these without a good reason, as they are incompatible with similar functions in Reader and Writer. They use a 4-byte length rather than an 8-byte length.

transfer blits len bytes from src to dst, advancing the lower bounds of both windows. It is an error if len > length src || len > length dst || phys_equal src dst.

memmove blits len bytes from src_pos to dst_pos in an iobuf, both relative to the lower bound of the window. The window is not advanced.

Iobuf has analogs of various Bigstring functions. These analogs advance by the amount written/read.

When there are no packets awaiting reception, recvmmsg_assume_fd_is_nonblocking returns <0 (actually, -EWOULDBLOCK/-EAGAIN), rather than raising Unix_error with EAGAIN/EWOULDBLOCK. This saves the allocation of an exception (and backtrace) in common cases, at the cost of callers having to handle but the return code and possible exception.