1/**
2 * D header file for Posix Message Queues
3 *
4 * Defines external functions required to manage Posix Message Queues
5 *
6 * mq_open(3)          open a message queue
7 * mq_close(3)         close a message queue
8 * mq_unlink(3)        remove a message queue
9 * mq_send(3)          send a message
10 * mq_receive(3)       receive a message
11 * mq_timedsend(3)     send a message with a timeout (linux specific)
12 * mq_timedreceive(3)  receive a message with a timeout (linux specific)
13 * mq_getattr(3)       get message queue attributes
14 * mq_setattr(3)       set message queue attributes
15 * mq_notify(3)        register asynchronous notify
16 *
17 * Copyright: Copyright (c) 2016 sociomantic labs. All rights reserved
18 * License:   $(HTTP www.boost.org/LICENSE_1_0.txt, Boost License 1.0).
19 * Authors:   Andreas Bok Andersen, Mathias Lang
20 * Standards: POSIX.1-2001.
21 * See_Also:  $(HTTP pubs.opengroup.org/onlinepubs/9699919799/basedefs/mqueue.h.html, Standard)
22 * Source: $(DRUNTIMESRC core/sys/posix/mqueue.d)
23 */
24module core.sys.posix.mqueue;
25
26import core.sys.posix.config;
27import core.sys.posix.signal;
28import core.sys.posix.time;
29
30version (Posix):
31version (CRuntime_Glibc):
32extern (C):
33@nogc nothrow:
34@system:
35
36
37/// Message queue descriptor.
38alias int mqd_t;
39
40/**
41 * Used in getting and setting the attributes of a message queue.
42 */
43struct mq_attr
44{
45    /// Message queue flags.
46    c_long mq_flags;
47    /// Maximum number of messages.
48    c_long mq_maxmsg;
49    /// Maximum message size.
50    c_long mq_msgsize;
51    /// Number of messages currently queued.
52    c_long mq_curmsgs;
53}
54
55
56/**
57 * Establish connection between a process and a message queue `name`.
58 *
59 * Note:
60 * Linux prototypes are:
61 * mqd_t mq_open (const(char)* name, int oflag);
62 * mqd_t mq_open (const(char)* name, int oflag, mode_t mode, mq_attr* attr);
63 *
64 * Params:
65 *   name   = Name of the message queue to open.
66 *   oflag  = determines the type of access used.
67 *            If `O_CREAT` is on `oflag`, the third argument is taken as a
68 *            `mode_t`, the mode of the created message queue.
69 *            If `O_CREAT` is on `oflag`, the fourth argument is taken as
70 *            a pointer to a `mq_attr' (message queue attributes).
71 *            If the fourth argument is `null`, default attributes are used.
72 *   ...    = varargs matching the function prototypes
73 *
74 * Returns:
75 *  Message queue descriptor or (mqd_t) -1 on error.
76 */
77mqd_t mq_open(const(char)* name, int oflag, ...);
78
79
80/**
81 * Closes the message queue descriptor mqdes.
82 *
83 * Params:
84 *   mqdes = Message queue descriptor to close.
85 *
86 * Returns:
87 *   On success mq_close() returns 0; on error, -1 is returned, with errno
88 *   set to indicate the error.
89 */
90int mq_close (mqd_t mqdes);
91
92
93/**
94 * Query status and attributes of message queue `mqdes`.
95 *
96 * Params:
97 *   mqdes  = Message queue descriptor.
98 *   mqstat = Buffer to fill with the message queue's attributes.
99 *
100 * Returns:
101 *   On success mq_getattr() return 0; on error, -1 is returned, with errno
102 *   set to indicate the error.
103 */
104int mq_getattr (mqd_t mqdes, mq_attr* mqstat);
105
106
107/*
108 * Set attributes associated with message queue `mqdes`
109 *
110 * Params:
111 *   mqdes   = Message queue descriptor.
112 *   newstat = non-null pointer to fill with attributes for `mqdes`.
113 *   oldstat = if not `null` it is filled with the old attributes.
114 *
115 * Returns:
116 *   On success mq_setattr() return 0; on error, -1 is returned, with errno
117 *   set to indicate the error.
118 */
119int mq_setattr (mqd_t mqdes, const(mq_attr)* newstat, mq_attr* oldstat);
120
121
122/**
123 * Remove the specified message queue `name`.
124 *
125 * Params:
126 *   name = Name of the queue to remove.
127 *
128 * Returns:
129 *   On success mq_unlink() returns 0; on error, -1 is returned, with errno
130 *   set to indicate the error.
131 */
132int mq_unlink (const(char)* name);
133
134
135/**
136 * Register for notification when a message is available
137 *
138 * Params:
139 *   mqdes        = Message queue descriptor.
140 *   notification = See `man 3 mq_notify` for details.
141 *
142 * Returns:
143 *   On success mq_notify() returns 0; on error, -1 is returned, with errno
144 *   set to indicate the error.
145 */
146int mq_notify (mqd_t mqdes, const(sigevent)* notification);
147
148
149/**
150 * Receive the oldest message with the highest priority the the message queue
151 *
152 * Params:
153 *   mqdes      = Message queue descriptor.
154 *   msg_ptr    = Buffer to write the message to
155 *   msg_len    = Size of the buffer provided as `msg_ptr`. Must be greater
156 *                than the mq_msgsize attribute of the queue.
157 *   msg_prio   = If not `null`, set to the priority of this message.
158 *
159 * Returns:
160 *   On success, mq_receive() returns the number of bytes in the received
161 *   message; on error, -1 is returned, with errno set to indicate the error
162 */
163ssize_t mq_receive (mqd_t mqdes, char* msg_ptr, size_t msg_len, uint* msg_prio);
164
165
166/**
167 * Receive the oldest message with the highest priority the the message queue,
168 * wait up to a certain timeout.
169 *
170 * Params:
171 *   mqdes       = Message queue descriptor.
172 *   msg_ptr     = Buffer to write the message to
173 *   msg_len     = Size of the buffer provided as `msg_ptr`. Must be greater
174 *                 than the mq_msgsize attribute of the queue.
175 *   msg_prio    = If not `null`, set to the priority of this message.
176 *   abs_timeout = Specify a ceiling on the time to block if the queue is empty.
177 *
178 * Returns:
179 *   On success, mq_receive() returns the number of bytes in the received
180 *   message; on error, -1 is returned, with errno set to indicate the error
181 */
182ssize_t mq_timedreceive (mqd_t mqdes, char* msg_ptr, size_t msg_len,
183                         uint* msg_prio, const(timespec)* abs_timeout);
184
185
186/**
187 * Add a message to a message queue.
188 *
189 * Params:
190 *   mqdes      = Message queue descriptor.
191 *   msg_ptr    = Buffer to read the message from
192 *   msg_len    = Size of the message provided via `msg_ptr`. Must be lower
193 *                or equal to the mq_msgsize attribute of the queue.
194 *   msg_prio   = Priority of this message.
195 *
196 * Returns:
197 *   On success, mq_send() return zero; on error, -1 is returned, with errno
198 *   set to indicate the error.
199 */
200int mq_send (mqd_t mqdes, const(char)* msg_ptr, size_t msg_len, uint msg_prio);
201
202
203/**
204 * Add a message to a message queue, block up to a certain time if the queue
205 * is full.
206 *
207 * Params:
208 *   mqdes      = Message queue descriptor.
209 *   msg_ptr    = Buffer to read the message from
210 *   msg_len    = Size of the message provided via `msg_ptr`. Must be lower
211 *                or equal to the mq_msgsize attribute of the queue.
212 *   msg_prio   = Priority of this message.
213 *   abs_timeout = Specify a ceiling on the time to block if the queue is empty.
214 *
215 * Returns:
216 *   On success, mq_timedsend() return zero; on error, -1 is returned,
217 *   with errno set to indicate the error.
218 *
219 */
220int mq_timedsend (mqd_t mqdes, const(char)* msg_ptr, size_t msg_len,
221                   uint msg_prio, const(timespec)* abs_timeout);
222