NAME
ibuf_add,
ibuf_add_ibuf, ibuf_add_h16,
ibuf_add_h32, ibuf_add_h64,
ibuf_add_n16, ibuf_add_n32,
ibuf_add_n64, ibuf_add_n8,
ibuf_add_zero, ibuf_close,
ibuf_data, ibuf_dynamic,
ibuf_fd_avail, ibuf_fd_get,
ibuf_fd_set, ibuf_free,
ibuf_from_buffer,
ibuf_from_ibuf, ibuf_get,
ibuf_get_ibuf, ibuf_get_h16,
ibuf_get_h32, ibuf_get_h64,
ibuf_get_n16, ibuf_get_n32,
ibuf_get_n64, ibuf_get_n8,
ibuf_left, ibuf_open,
ibuf_reserve, ibuf_rewind,
ibuf_seek, ibuf_set,
ibuf_set_h16, ibuf_set_h32,
ibuf_set_h64, ibuf_set_n16,
ibuf_set_n32, ibuf_set_n64,
ibuf_set_n8, ibuf_size,
ibuf_skip, ibuf_truncate,
ibuf_write, msgbuf_clear,
msgbuf_init,
msgbuf_queuelen,
msgbuf_write —
save buffer API for basic IO
SYNOPSIS
#include
<sys/queue.h>
#include <imsg.h>
int
ibuf_add(struct
ibuf *buf, const void
*data, size_t
len);
int
ibuf_add_ibuf(struct
ibuf *buf, const struct
ibuf *from);
int
ibuf_add_h16(struct
ibuf *buf, uint64_t
value);
int
ibuf_add_h32(struct
ibuf *buf, uint64_t
value);
int
ibuf_add_h64(struct
ibuf *buf, uint64_t
value);
int
ibuf_add_n16(struct
ibuf *buf, uint64_t
value);
int
ibuf_add_n32(struct
ibuf *buf, uint64_t
value);
int
ibuf_add_n64(struct
ibuf *buf, uint64_t
value);
int
ibuf_add_n8(struct
ibuf *buf, uint64_t
value);
int
ibuf_add_zero(struct
ibuf *buf, size_t
len);
void
ibuf_close(struct
msgbuf *msgbuf, struct
ibuf *buf);
void *
ibuf_data(struct
ibuf *buf);
struct ibuf *
ibuf_dynamic(size_t
len, size_t
max);
int
ibuf_fd_avail(struct
ibuf *buf);
int
ibuf_fd_get(struct
ibuf *buf);
void
ibuf_fd_set(struct
ibuf *buf, int
fd);
void
ibuf_free(struct
ibuf *buf);
void
ibuf_from_buffer(struct
ibuf *buf, void
*data, size_t
len);
void
ibuf_from_ibuf(struct
ibuf *buf, const ibuf
*from);
int
ibuf_get(struct
ibuf *buf, void
*data, size_t
len);
int
ibuf_get_ibuf(struct
ibuf *buf, size_t
len, struct ibuf
*new);
int
ibuf_get_h16(struct
ibuf *buf, uint16_t
*value);
int
ibuf_get_h32(struct
ibuf *buf, uint32_t
*value);
int
ibuf_get_h64(struct
ibuf *buf, uint64_t
*value);
int
ibuf_get_n16(struct
ibuf *buf, uint16_t
*value);
int
ibuf_get_n32(struct
ibuf *buf, uint32_t
*value);
int
ibuf_get_n64(struct
ibuf *buf, uint64_t
*value);
int
ibuf_get_n8(struct
ibuf *buf, uint8_t
*value);
size_t
ibuf_left(const
struct ibuf *buf);
struct ibuf *
ibuf_open(size_t
len);
void *
ibuf_reserve(struct
ibuf *buf, size_t
len);
void
ibuf_rewind(struct
ibuf *buf);
void *
ibuf_seek(struct
ibuf *buf, size_t
pos, size_t
len);
int
ibuf_set(struct
ibuf *buf, size_t
pos, const void
*data, size_t
len);
int
ibuf_set_h16(struct
ibuf *buf, size_t
pos, uint64_t
value);
int
ibuf_set_h32(struct
ibuf *buf, size_t
pos, uint64_t
value);
int
ibuf_set_h64(struct
ibuf *buf, size_t
pos, uint64_t
value);
int
ibuf_set_n16(struct
ibuf *buf, size_t
pos, uint64_t
value);
int
ibuf_set_n32(struct
ibuf *buf, size_t
pos, uint64_t
value);
int
ibuf_set_n64(struct
ibuf *buf, size_t
pos, uint64_t
value);
int
ibuf_set_n8(struct
ibuf *buf, size_t
pos, uint64_t
value);
size_t
ibuf_size(const
struct ibuf *buf);
int
ibuf_skip(struct
ibuf *buf, size_t
len);
int
ibuf_truncate(struct
ibuf *buf, size_t
len);
int
ibuf_write(struct
msgbuf *msgbuf);
void
msgbuf_init(struct
msgbuf *msgbuf);
void
msgbuf_clear(struct
msgbuf *msgbuf);
uint32_t
msgbuf_queuelen(struct
msgbuf *msgbuf);
int
msgbuf_write(struct
msgbuf *msgbuf);
DESCRIPTION
The ibuf API defines functions to manipulate buffers, used for
example to construct imsgs with
imsg_create(3). A struct ibuf is a single
buffer. It has a maximum size, a read and a write position. Buffers should
be either constructed with the various
ibuf_add()
and ibuf_set() functions or consumed with the
various ibuf_get() functions. A
struct msgbuf is used to queue the output buffers for
transmission.
ibuf_add()
appends a block of data to buf. 0 is returned on
success and -1 on failure.
ibuf_add_ibuf()
appends the buffer from to buf.
0 is returned on success and -1 on failure.
ibuf_add_h16(),
ibuf_add_h32(),
and
ibuf_add_h64()
add a 2-byte, 4-byte, and 8-byte value to
buf in host byte order. This function checks
value to not overflow. 0 is returned on success and -1
on failure.
ibuf_add_n8(),
ibuf_add_n16(),
ibuf_add_n32(),
and
ibuf_add_n64()
add a 1-byte, 2-byte, 4-byte, and 8-byte value to
buf in network byte order. This function checks
value to not overflow. 0 is returned on success and -1
on failure.
ibuf_add_zero()
appends a block of zeros to buf. 0 is returned on
success and -1 on failure.
ibuf_close()
appends buf to msgbuf ready to
be sent.
ibuf_data()
returns the pointer to the internal buffer. This function should only be
used together with ibuf_size() to process a
previously generated buffer.
ibuf_dynamic()
allocates a resizeable buffer of initial length len
and maximum size max. Buffers allocated with
ibuf_dynamic() are automatically grown if necessary
when data is added.
ibuf_fd_avail(),
ibuf_fd_get()
and ibuf_fd_set() are functions to check, get and
set the file descriptor assigned to buf. After calling
ibuf_fd_set() the file descriptor is part of the
buf and will be transmitted or closed by the ibuf API.
Any previously set file descriptor will be closed before assigning a new
descriptor. ibuf_fd_get() returns the file
descriptor and passes the responsibility to track the descriptor back to the
program. ibuf_fd_avail() returns true if there is a
file descriptor set on buf.
ibuf_free()
frees buf and any associated storage, and closes any
file descriptor set with
ibuf_fd_set().
If buf is a NULL pointer, no action occurs.
ibuf_from_buffer()
initializes the passed buf to point at
data and spanning len bytes. The
returned buffer can be read using the various
ibuf_get() functions .
ibuf_from_ibuf()
duplicates the from ibuf into
buf without modifying from. This
allows safely peeking into an ibuf without consuming data.
ibuf_get()
consumes a block of data from buf spanning
len bytes. 0 is returned on success and -1 on
failure.
ibuf_get_ibuf()
consumes len bytes from the buffer
buf and returns it in new
covering this region. The data in this buffer is only valid as long as
buf remains valid . There is no need to deallocate
new using ibuf_free(). 0 is
returned on success and -1 on failure.
ibuf_get_h16(),
ibuf_get_h32(),
and
ibuf_get_h64()
get a 2-byte, 4-byte, and 8-byte value from
buf without altering byte order. 0 is returned on
success and -1 on failure.
ibuf_get_n8(),
ibuf_get_n16(),
ibuf_get_n32(),
and
ibuf_get_n64()
get a 1-byte, 2-byte, 4-byte, and 8-byte value from
buf converting the value from network to host byte
order. 0 is returned on success and -1 on failure.
The
ibuf_open()
function allocates a fixed-length buffer. The buffer may not be resized and
may contain a maximum of len bytes. On success
ibuf_open() returns a pointer to the buffer; on
failure it returns NULL.
ibuf_reserve()
is used to reserve len bytes in
buf. A pointer to the start of the reserved space is
returned, or NULL on error.
ibuf_rewind()
resets the read offset to the start of the buffer.
ibuf_seek()
returns a pointer to the part of the buffer at offset
pos and of extent len. NULL is
returned if the requested range is outside the part of the buffer in
use.
ibuf_set()
replaces a part of buf at offset
pos with the data of extent
len. 0 is returned on success and -1 on failure.
ibuf_set_h16(),
ibuf_set_h32()
and
ibuf_set_h64()
replace a 2-byte, 4-byte or 8-byte value at offset
pos in the buffer buf in host
byte order. This function checks value to not
overflow. 0 is returned on success and -1 on failure.
ibuf_set_n8(),
ibuf_set_n16(),
ibuf_set_n32()
and
ibuf_set_n64()
replace a 1-byte, 2-byte, 4-byte or 8-byte value at
offset pos in the buffer buf in
network byte order. This function checks value to not
overflow. 0 is returned on success and -1 on failure.
ibuf_size()
and
ibuf_left()
are functions which return the total bytes used and available in
buf, respectively.
ibuf_skip()
advances the read position in buf by
len bytes. 0 is returned on success and -1 on
failure.
ibuf_truncate()
truncates the buffer to len bytes if necessary zero
extending the buffer. 0 is returned on success and -1 on failure.
The
ibuf_write()
routine transmits as many pending buffers as possible from
msgbuf using
writev(2).
It returns 1 if it succeeds, -1 on error and 0 when no buffers were pending
or an EOF condition on the socket is detected. Temporary resource shortages
are returned with errno EAGAIN and require the
application to retry again in the future.
The
msgbuf_init()
function initializes msgbuf so that buffers may be
appended to it. The fd member should also be set
directly before msgbuf_write() is used.
msgbuf_clear()
empties a msgbuf, removing and discarding any queued buffers.
msgbuf_queuelen()
returns the number of messages queued in msgbuf. This
function returns 0 if no messages are pending for transmission.
The
msgbuf_write()
routine calls sendmsg(2) to transmit buffers queued in
msgbuf. It returns 1 if it succeeds, -1 on error, and
0 when the queue was empty or an EOF condition on the socket is detected.
Temporary resource shortages are returned with errno
EAGAIN and require the application to retry again in
the future.