NAME

LIBRARY

SYNOPSIS

void
imsg_init(struct imsgbuf *ibuf, int fd);

ssize_t
imsg_read(struct imsgbuf *ibuf);

ssize_t
imsg_get(struct imsgbuf *ibuf, struct imsg *imsg);

int
imsg_compose(struct imsgbuf *ibuf, u_int32_t type, uint32_t peerid, pid_t pid, int fd, const void *data, u_int16_t datalen);

int
imsg_composev(struct imsgbuf *ibuf, u_int32_t type, u_int32_t peerid, pid_t pid, int fd, const struct iovec *iov, int iovcnt);

struct ibuf *
imsg_create(struct imsgbuf *ibuf, u_int32_t type, u_int32_t peerid, pid_t pid, u_int16_t datalen);

int
imsg_add(struct ibuf *buf, const void *data, u_int16_t datalen);

void
imsg_close(struct imsgbuf *ibuf, struct ibuf *msg);

void
imsg_free(struct imsg *imsg);

int
imsg_flush(struct imsgbuf *ibuf);

void
imsg_clear(struct imsgbuf *ibuf);

struct ibuf *
ibuf_open(size_t len);

struct ibuf *
ibuf_dynamic(size_t len, size_t max);

int
ibuf_add(struct ibuf *buf, const void *data, size_t len);

void *
ibuf_reserve(struct ibuf *buf, size_t len);

void *
ibuf_seek(struct ibuf *buf, size_t pos, size_t len);

size_t
ibuf_size(struct ibuf *buf);

size_t
ibuf_left(struct ibuf *buf);

void
ibuf_close(struct msgbuf *msgbuf, struct ibuf *buf);

int
ibuf_write(struct msgbuf *msgbuf);

void
ibuf_free(struct ibuf *buf);

void
msgbuf_init(struct msgbuf *msgbuf);

void
msgbuf_clear(struct msgbuf *msgbuf);

int
msgbuf_write(struct msgbuf *msgbuf);

void
msgbuf_drain(struct msgbuf *msgbuf, size_t n);

DESCRIPTION

A program using these functions should be linked with -lutil.

The basic imsg_init structure is the imsgbuf, which wraps a file descriptor and represents one side of a channel on which messages are sent and received:

struct imsgbuf {
	TAILQ_HEAD(, imsg_fd)	fds;
	struct ibuf_read	r;
	struct msgbuf		w;
	int			fd;
	pid_t			pid;
};

imsg_init() is a routine which initializes ibuf as one side of a channel associated with fd. The file descriptor is used to send and receive messages, but is not closed by any of the imsg functions. An imsgbuf is initialized with the w member as the output buffer queue, fd with the file descriptor passed to imsg_init() and the other members for internal use only.

The imsg_clear() function frees any data allocated as part of an imsgbuf.

imsg_create(), imsg_add() and imsg_close() are generic construction routines for messages that are to be sent using an imsgbuf.

imsg_create() creates a new message with header specified by type, peerid and pid. A pid of zero uses the process ID returned by getpid(2) when ibuf was initialized. In addition to this common imsg header, datalen bytes of space may be reserved for attaching to this imsg. This space is populated using imsg_add(). Additionally, the file descriptor fd may be passed over the socket to the other process. If fd is given, it is closed in the sending program after the message is sent. A value of -1 indicates no file descriptor should be passed. imsg_create() returns a pointer to a new message if it succeeds, NULL otherwise.

imsg_add() appends to imsg len bytes of ancillary data pointed to by buf. It returns len if it succeeds, -1 otherwise.

imsg_close() completes creation of imsg by adding it to imsgbuf output buffer.

imsg_compose() is a routine which is used to quickly create and queue an imsg. It takes the same parameters as the imsg_create(), imsg_add() and imsg_close() routines, except that only one ancillary data buffer can be provided. This routine returns 1 if it succeeds, -1 otherwise.

imsg_composev() is similar to imsg_compose(). It takes the same parameters, except that the ancillary data buffer is specified by iovec.

imsg_flush() is a function which calls msgbuf_write() in a loop until all imsgs in the output buffer are sent. It returns 0 if it succeeds, -1 otherwise.

The imsg_read() routine reads pending data with recvmsg(2) and queues it as individual messages on imsgbuf. It returns the number of bytes read on success, or -1 on error. A return value of -1 from imsg_read() invalidates imsgbuf, and renders it suitable only for passing to imsg_clear().

imsg_get() fills in an individual imsg pending on imsgbuf into the structure pointed to by imsg. It returns the total size of the message, 0 if no messages are ready, or -1 for an error. Received messages are returned as a struct imsg, which must be freed by imsg_free() when no longer required. struct imsg has this form:

struct imsg {
	struct imsg_hdr	 hdr;
	int		 fd;
	void		*data;
};

struct imsg_hdr {
	u_int32_t	 type;
	u_int16_t	 len;
	u_int16_t	 flags;
	u_int32_t	 peerid;
	u_int32_t	 pid;
};

The header members are:

In addition, struct imsg has the following:

The IMSG_HEADER_SIZE define is the size of the imsg message header, which may be subtracted from the len member of struct imsg_hdr to obtain the length of any additional data passed with the message.

MAX_IMSGSIZE is defined as the maximum size of a single imsg, currently 16384 bytes.

BUFFERS

struct ibuf {
	TAILQ_ENTRY(ibuf)	 entry;
	u_char			*buf;
	size_t			 size;
	size_t			 max;
	size_t			 wpos;
	size_t			 rpos;
	int			 fd;
};

struct msgbuf {
	TAILQ_HEAD(, ibuf)	 bufs;
	u_int32_t		 queued;
	int			 fd;
};

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_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_add() is a routine which appends a block of data to buf. 0 is returned on success and -1 on failure.

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_seek() is a function which 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_size() and ibuf_left() are functions which return the total bytes used and available in buf respectively.

ibuf_close() appends buf to msgbuf ready to be sent.

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.

ibuf_free() frees buf and any associated storage.

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.

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.

msgbuf_drain() discards data from buffers queued in msgbuf until n bytes have been removed or msgbuf is empty.

EXAMPLES

struct imsgbuf	parent_ibuf, child_ibuf;
int		imsg_fds[2];

if (socketpair(AF_UNIX, SOCK_STREAM, PF_UNSPEC, imsg_fds) == -1)
	err(1, "socketpair");

switch (fork()) {
case -1:
	err(1, "fork");
case 0:
	/* child */
	close(imsg_fds[0]);
	imsg_init(&child_ibuf, imsg_fds[1]);
	exit(child_main(&child_ibuf));
}

/* parent */
close(imsg_fds[1]);
imsg_init(&parent_ibuf, imsg_fds[0]);
exit(parent_main(&parent_ibuf));

Messages may then be composed and queued on the imsgbuf, for example using the imsg_compose() function:

enum imsg_type {
	IMSG_A_MESSAGE,
	IMSG_MESSAGE2
};

int
child_main(struct imsgbuf *ibuf)
{
	int	idata;
	...
	idata = 42;
	imsg_compose(ibuf, IMSG_A_MESSAGE,
		0, 0, -1, &idata, sizeof idata);
	...
}

A mechanism such as poll(2) or the event(3) library is used to monitor the socket file descriptor. When the socket is ready for writing, queued messages are transmitted with msgbuf_write():

	if (msgbuf_write(&ibuf->w) <= 0 && errno != EAGAIN) {
		/* handle write failure */
	}

And when ready for reading, messages are first received using imsg_read() and then extracted with imsg_get():

void
dispatch_imsg(struct imsgbuf *ibuf)
{
	struct imsg	imsg;
	ssize_t         n, datalen;
	int		idata;

	if ((n = imsg_read(ibuf)) == -1 || n == 0) {
		/* handle socket error */
	}

	for (;;) {
		if ((n = imsg_get(ibuf, &imsg)) == -1) {
			/* handle read error */
		}
		if (n == 0)	/* no more messages */
			return;
		datalen = imsg.hdr.len - IMSG_HEADER_SIZE;

		switch (imsg.hdr.type) {
		case IMSG_A_MESSAGE:
			if (datalen < sizeof idata) {
				/* handle corrupt message */
			}
			memcpy(&idata, imsg.data, sizeof idata);
			/* handle message received */
			break;
		...
		}

		imsg_free(&imsg);
	}
}

SEE ALSO