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  */
24 module core.sys.posix.mqueue;
25 
26 import core.sys.posix.config;
27 import core.sys.posix.signal;
28 import core.sys.posix.time;
29 
30 version (Posix):
31 version (CRuntime_Glibc):
32 extern (C):
33 @nogc nothrow:
34 
35 
36 /// Message queue descriptor.
37 alias int mqd_t;
38 
39 /**
40  * Used in getting and setting the attributes of a message queue.
41  */
42 struct mq_attr
43 {
44     /// Message queue flags.
45     c_long mq_flags;
46     /// Maximum number of messages.
47     c_long mq_maxmsg;
48     /// Maximum message size.
49     c_long mq_msgsize;
50     /// Number of messages currently queued.
51     c_long mq_curmsgs;
52 }
53 
54 
55 /**
56  * Establish connection between a process and a message queue `name`.
57  *
58  * Note:
59  * Linux prototypes are:
60  * mqd_t mq_open (const(char)* name, int oflag);
61  * mqd_t mq_open (const(char)* name, int oflag, mode_t mode, mq_attr* attr);
62  *
63  * Params:
64  *   name   = Name of the message queue to open.
65  *   oflag  = determines the type of access used.
66  *            If `O_CREAT` is on `oflag`, the third argument is taken as a
67  *            `mode_t`, the mode of the created message queue.
68  *            If `O_CREAT` is on `oflag`, the fourth argument is taken as
69  *            a pointer to a `mq_attr' (message queue attributes).
70  *            If the fourth argument is `null`, default attributes are used.
71  *   ...    = varargs matching the function prototypes
72  *
73  * Returns:
74  *  Message queue descriptor or (mqd_t) -1 on error.
75  */
76 mqd_t mq_open(const(char)* name, int oflag, ...);
77 
78 
79 /**
80  * Closes the message queue descriptor mqdes.
81  *
82  * Params:
83  *   mqdes = Message queue descriptor to close.
84  *
85  * Returns:
86  *   On success mq_close() returns 0; on error, -1 is returned, with errno
87  *   set to indicate the error.
88  */
89 int mq_close (mqd_t mqdes);
90 
91 
92 /**
93  * Query status and attributes of message queue `mqdes`.
94  *
95  * Params:
96  *   mqdes  = Message queue descriptor.
97  *   mqstat = Buffer to fill with the message queue's attributes.
98  *
99  * Returns:
100  *   On success mq_getattr() return 0; on error, -1 is returned, with errno
101  *   set to indicate the error.
102  */
103 int mq_getattr (mqd_t mqdes, mq_attr* mqstat);
104 
105 
106 /*
107  * Set attributes associated with message queue `mqdes`
108  *
109  * Params:
110  *   mqdes   = Message queue descriptor.
111  *   newstat = non-null pointer to fill with attributes for `mqdes`.
112  *   oldstat = if not `null` it is filled with the old attributes.
113  *
114  * Returns:
115  *   On success mq_setattr() return 0; on error, -1 is returned, with errno
116  *   set to indicate the error.
117  */
118 int mq_setattr (mqd_t mqdes, const(mq_attr)* newstat, mq_attr* oldstat);
119 
120 
121 /**
122  * Remove the specified message queue `name`.
123  *
124  * Params:
125  *   name = Name of the queue to remove.
126  *
127  * Returns:
128  *   On success mq_unlink() returns 0; on error, -1 is returned, with errno
129  *   set to indicate the error.
130  */
131 int mq_unlink (const(char)* name);
132 
133 
134 /**
135  * Register for notification when a message is available
136  *
137  * Params:
138  *   mqdes        = Message queue descriptor.
139  *   notification = See `man 3 mq_notify` for details.
140  *
141  * Returns:
142  *   On success mq_notify() returns 0; on error, -1 is returned, with errno
143  *   set to indicate the error.
144  */
145 int mq_notify (mqd_t mqdes, const(sigevent)* notification);
146 
147 
148 /**
149  * Receive the oldest message with the highest priority the message queue
150  *
151  * Params:
152  *   mqdes      = Message queue descriptor.
153  *   msg_ptr    = Buffer to write the message to
154  *   msg_len    = Size of the buffer provided as `msg_ptr`. Must be greater
155  *                than the mq_msgsize attribute of the queue.
156  *   msg_prio   = If not `null`, set to the priority of this message.
157  *
158  * Returns:
159  *   On success, mq_receive() returns the number of bytes in the received
160  *   message; on error, -1 is returned, with errno set to indicate the error
161  */
162 ssize_t mq_receive (mqd_t mqdes, char* msg_ptr, size_t msg_len, uint* msg_prio);
163 
164 
165 /**
166  * Receive the oldest message with the highest priority the message queue,
167  * wait up to a certain timeout.
168  *
169  * Params:
170  *   mqdes       = Message queue descriptor.
171  *   msg_ptr     = Buffer to write the message to
172  *   msg_len     = Size of the buffer provided as `msg_ptr`. Must be greater
173  *                 than the mq_msgsize attribute of the queue.
174  *   msg_prio    = If not `null`, set to the priority of this message.
175  *   abs_timeout = Specify a ceiling on the time to block if the queue is empty.
176  *
177  * Returns:
178  *   On success, mq_receive() returns the number of bytes in the received
179  *   message; on error, -1 is returned, with errno set to indicate the error
180  */
181 pragma(mangle, muslRedirTime64Mangle!("mq_timedreceive", "__mq_timedreceive_time64"))
182 ssize_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  */
200 int 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  */
220 pragma(mangle, muslRedirTime64Mangle!("mq_timedsend", "__mq_timedsend_time64"))
221 int mq_timedsend (mqd_t mqdes, const(char)* msg_ptr, size_t msg_len,
222                    uint msg_prio, const(timespec)* abs_timeout);