IBUF_ADD(3)

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.

SEE ALSO
socketpair(2), imsg_init(3), unix(4)