NAME
buffer_get, buffer_getv, buffer_getall, buffer_getvall, buffer_getnofill, buffer_getvnofill, buffer_getallnofill, buffer_getvallnofill - load data into a reading I/O buffer
SYNOPSIS
#include <limb/buffer.h>
ssize_t buffer_get(buffer *buf, char *dst, size_t dlen) ssize_t buffer_getv(buffer *buf, struct iovec *v, unsigned vlen) int buffer_getall(buffer *buf, char *dst, size_t dlen, size_t *written) int buffer_getvall(buffer *buf, const struct iovec *v, unsigned vlen, size_t *written) size_t buffer_getnofill(buffer *buf, char *dst, size_t dlen) size_t buffer_getvnofill(buffer *buf, const struct iovec *v, unsigned vlen) int buffer_getallnofill(buffer *buf, char *dst, size_t dlen) int buffer_getvallnofill(buffer *buf, const struct iovec *v, unsigned vlen)
DESCRIPTION
The buffer_get() function will copy into the memory pointed by dst of length
dlen data from the buffer pointed by buf. It will try to put as much data as
possible, i.e. place dlen bytes, filing the buffer if needed. It might copy
less if end-of-file was reached.
Any data copied from the buffer is then "removed" from it, i.e. the corresponding space in the buffer's internal memory becomes available.
The buffer_getv() function is similar to buffer_get() only copying data into
the memory as described by the array of vectors pointed by v of length vlen.
The buffer_getall() function is similar to buffer_get(), except that it will
copy data into the memory location pointed by dst starting at offset whose
value is pointed by written (usually 0), updating it as it writes data read
from the buffer.
The buffer_getvall() function is similar to buffer_getall() only copying
data into the memory as described by the array of vectors pointed by v of
length vlen.
The buffer_getnofill() macro is similar to buffer_get() except that it
will not fill the buffer, returning the size of data actually copied into the
memory pointed by dst - which may or may not be the full dlen size.
The buffer_getvnofill() macro is similar to buffer_getnofill() only copying
data into the memory as described by the array of vectors pointed by v of
length vlen.
The buffer_getallnofill() function is similar to buffer_getnofill() except
that if the entirety of the data cannot be copied from the buffer, it fails
without removing any data from it.
The buffer_getvallnofill() function is similar to buffer_getallnofill() only
copying data into the memory as described by the array of vectors pointed by v
of length vlen.
RETURN VALUE
The buffer_get() and buffer_getv() functions return the size of data read
from the buffer (and copied into the specified location(s)) on success, which
may be less than requested if end-of-file was reached.
Otherwise they return -1 and set errno to indicate the error.
The buffer_getall() and buffer_getvall() functions return 1 when all
requested data have been copied from the buffer. They return 0 when less data
was copied (possibly none) and the buffer couldn't be filled due to EAGAIN or
EWOULDBLOCK errors from the buffer's operational function.
Otherwise, they return -1 and set errno to indicate the error.
The buffer_getnofill() and buffer_getvnofill() macros return the amount of
data copied from the buffer. They cannot fail, though the returned amount might
be less than requested, even 0 if the buffer if empty.
The buffer_getallnofill() and buffer_getvallnofill() functions return 1 when
all requested data was copied from the buffer. Otherwise they return 0 set set
errno to indicate the error.
ERRORS
The buffer_get() and buffer_getv() functions may fail for any of the errors
for their operational function, as set via e.g. buffer_init(3).
The buffer_getall() and buffer_getvall() functions may fail if :
EINVAL
The value pointed by written is more than available in destination (e.g.
more than dlen).
EPIPE
End of file was reached, i.e. the operational function returned 0.
The buffer_getall() and buffer_getvall() functions may also fail and set
errno for any of the errors for their operational function, save EAGAIN or
EWOULDBLOCK for which they would return 0 instead.
The buffer_getallnofill() and buffer_getvallnofill() functions may fail if :
ENOBUFS
The requested amount of data cannot be read from the buffer, i.e. there isn't that much data in the buffer's internal memory.