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 @system: 35 36 37 /// Message queue descriptor. 38 alias int mqd_t; 39 40 /** 41 * Used in getting and setting the attributes of a message queue. 42 */ 43 struct 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 */ 77 mqd_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 */ 90 int 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 */ 104 int 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 */ 119 int 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 */ 132 int 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 */ 146 int 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 */ 163 ssize_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 */ 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 int mq_timedsend (mqd_t mqdes, const(char)* msg_ptr, size_t msg_len, 221 uint msg_prio, const(timespec)* abs_timeout); 222