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);