1 .\" $OpenBSD: imsg_init.3,v 1.13 2015/07/11 16:23:59 deraadt Exp $
3 .\" Copyright (c) 2010 Nicholas Marriott <nicm@openbsd.org>
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 .\" WHATSOEVER RESULTING FROM LOSS OF MIND, USE, DATA OR PROFITS, WHETHER
14 .\" IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
15 .\" OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 .Dd $Mdocdate: July 11 2015 $
46 .Nd IPC messaging functions
53 .Fn imsg_init "struct imsgbuf *ibuf" "int fd"
55 .Fn imsg_read "struct imsgbuf *ibuf"
57 .Fn imsg_get "struct imsgbuf *ibuf" "struct imsg *imsg"
59 .Fn imsg_compose "struct imsgbuf *ibuf" "u_int32_t type" "uint32_t peerid" \
60 "pid_t pid" "int fd" "const void *data" "u_int16_t datalen"
62 .Fn imsg_composev "struct imsgbuf *ibuf" "u_int32_t type" "u_int32_t peerid" \
63 "pid_t pid" "int fd" "const struct iovec *iov" "int iovcnt"
65 .Fn imsg_create "struct imsgbuf *ibuf" "u_int32_t type" "u_int32_t peerid" \
66 "pid_t pid" "u_int16_t datalen"
68 .Fn imsg_add "struct ibuf *buf" "const void *data" "u_int16_t datalen"
70 .Fn imsg_close "struct imsgbuf *ibuf" "struct ibuf *msg"
72 .Fn imsg_free "struct imsg *imsg"
74 .Fn imsg_flush "struct imsgbuf *ibuf"
76 .Fn imsg_clear "struct imsgbuf *ibuf"
78 .Fn ibuf_open "size_t len"
80 .Fn ibuf_dynamic "size_t len" "size_t max"
82 .Fn ibuf_add "struct ibuf *buf" "const void *data" "size_t len"
84 .Fn ibuf_reserve "struct ibuf *buf" "size_t len"
86 .Fn ibuf_seek "struct ibuf *buf" "size_t pos" "size_t len"
88 .Fn ibuf_size "struct ibuf *buf"
90 .Fn ibuf_left "struct ibuf *buf"
92 .Fn ibuf_close "struct msgbuf *msgbuf" "struct ibuf *buf"
94 .Fn ibuf_write "struct msgbuf *msgbuf"
96 .Fn ibuf_free "struct ibuf *buf"
98 .Fn msgbuf_init "struct msgbuf *msgbuf"
100 .Fn msgbuf_clear "struct msgbuf *msgbuf"
102 .Fn msgbuf_write "struct msgbuf *msgbuf"
104 .Fn msgbuf_drain "struct msgbuf *msgbuf" "size_t n"
108 functions provide a simple mechanism for communication between processes
110 Each transmitted message is guaranteed to be presented to the receiving program
112 They are commonly used in privilege separated processes, where processes with
113 different rights are required to cooperate.
115 A program using these functions should be linked with
122 which wraps a file descriptor and represents one side of a channel on which
123 messages are sent and received:
124 .Bd -literal -offset indent
126 TAILQ_HEAD(, imsg_fd) fds;
135 is a routine which initializes
137 as one side of a channel associated with
139 The file descriptor is used to send and receive messages,
140 but is not closed by any of the imsg functions.
141 An imsgbuf is initialized with the
143 member as the output buffer queue,
145 with the file descriptor passed to
147 and the other members for internal use only.
151 function frees any data allocated as part of an imsgbuf.
157 are generic construction routines for messages that are to be sent using an
161 creates a new message with header specified by
168 of zero uses the process ID returned by
173 In addition to this common imsg header,
175 bytes of space may be reserved for attaching to this imsg.
176 This space is populated using
178 Additionally, the file descriptor
180 may be passed over the socket to the other process.
183 is given, it is closed in the sending program after the message is sent.
184 A value of \-1 indicates no file descriptor should be passed.
186 returns a pointer to a new message if it succeeds, NULL otherwise.
192 bytes of ancillary data pointed to by
196 if it succeeds, \-1 otherwise.
199 completes creation of
206 is a routine which is used to quickly create and queue an imsg.
207 It takes the same parameters as the
213 except that only one ancillary data buffer can be provided.
214 This routine returns 1 if it succeeds, \-1 otherwise.
219 It takes the same parameters, except that the ancillary data buffer is specified
224 is a function which calls
226 in a loop until all imsgs in the output buffer are sent.
227 It returns 0 if it succeeds, \-1 otherwise.
231 routine reads pending data with
233 and queues it as individual messages on
235 It returns the number of bytes read on success, or \-1 on error.
236 A return value of \-1 from
240 and renders it suitable only for passing to
244 fills in an individual imsg pending on
246 into the structure pointed to by
248 It returns the total size of the message, 0 if no messages are ready, or \-1
250 Received messages are returned as a
252 which must be freed by
254 when no longer required.
257 .Bd -literal -offset indent
273 The header members are:
274 .Bl -tag -width Ds -offset indent
276 A integer identifier, typically used to express the meaning of the message.
278 The total length of the imsg, including the header and any ancillary data
279 transmitted with the message (pointed to by the
281 member of the message itself).
283 Flags used internally by the imsg functions: should not be used by application
286 32-bit values specified on message creation and free for any use by the
287 caller, normally used to identify the message sender.
293 .Bl -tag -width Ds -offset indent
295 The file descriptor specified when the message was created and passed using the
296 socket control message API, or \-1 if no file descriptor was sent.
298 A pointer to the ancillary data transmitted with the imsg.
301 The IMSG_HEADER_SIZE define is the size of the imsg message header, which
302 may be subtracted from the
306 to obtain the length of any additional data passed with the message.
308 MAX_IMSGSIZE is defined as the maximum size of a single imsg, currently
311 The imsg API defines functions to manipulate buffers, used internally and during
312 construction of imsgs with
316 is a single buffer and a
318 a queue of output buffers for transmission:
319 .Bd -literal -offset indent
321 TAILQ_ENTRY(ibuf) entry;
331 TAILQ_HEAD(, ibuf) bufs;
339 function allocates a fixed-length buffer.
340 The buffer may not be resized and may contain a maximum of
345 returns a pointer to the buffer; on failure it returns NULL.
348 allocates a resizable buffer of initial length
352 Buffers allocated with
354 are automatically grown if necessary when data is added.
357 is a routine which appends a block of data to
359 0 is returned on success and \-1 on failure.
366 A pointer to the start of the reserved space is returned, or NULL on error.
369 is a function which returns a pointer to the part of the buffer at offset
373 NULL is returned if the requested range is outside the part of the buffer
379 are functions which return the total bytes used and available in
392 routine transmits as many pending buffers as possible from
396 It returns 1 if it succeeds, \-1 on error and 0 when no buffers were
397 pending or an EOF condition on the socket is detected.
398 Temporary resource shortages are returned with errno
400 and require the application to retry again in the future.
405 and any associated storage.
411 so that buffers may be appended to it.
414 member should also be set directly before
419 empties a msgbuf, removing and discarding any queued buffers.
425 to transmit buffers queued in
427 It returns 1 if it succeeds, \-1 on error, and 0 when the queue was empty
428 or an EOF condition on the socket is detected.
429 Temporary resource shortages are returned with errno
431 and require the application to retry again in the future.
434 discards data from buffers queued in
438 bytes have been removed or
442 In a typical program, a channel between two processes is created with
446 created around one file descriptor in each process:
447 .Bd -literal -offset indent
448 struct imsgbuf parent_ibuf, child_ibuf;
451 if (socketpair(AF_UNIX, SOCK_STREAM, PF_UNSPEC, imsg_fds) == -1)
452 err(1, "socketpair");
460 imsg_init(&child_ibuf, imsg_fds[1]);
461 exit(child_main(&child_ibuf));
466 imsg_init(&parent_ibuf, imsg_fds[0]);
467 exit(parent_main(&parent_ibuf));
470 Messages may then be composed and queued on the
472 for example using the
475 .Bd -literal -offset indent
482 child_main(struct imsgbuf *ibuf)
487 imsg_compose(ibuf, IMSG_A_MESSAGE,
488 0, 0, -1, &idata, sizeof idata);
497 library is used to monitor the socket file descriptor.
498 When the socket is ready for writing, queued messages are transmitted with
500 .Bd -literal -offset indent
501 if (msgbuf_write(&ibuf-\*(Gtw) \*(Lt= 0 && errno != EAGAIN) {
502 /* handle write failure */
506 And when ready for reading, messages are first received using
508 and then extracted with
510 .Bd -literal -offset indent
512 dispatch_imsg(struct imsgbuf *ibuf)
518 if ((n = imsg_read(ibuf)) == -1 || n == 0) {
519 /* handle socket error */
523 if ((n = imsg_get(ibuf, &imsg)) == -1) {
524 /* handle read error */
526 if (n == 0) /* no more messages */
528 datalen = imsg.hdr.len - IMSG_HEADER_SIZE;
530 switch (imsg.hdr.type) {
532 if (datalen \*(Lt sizeof idata) {
533 /* handle corrupt message */
535 memcpy(&idata, imsg.data, sizeof idata);
536 /* handle message received */