git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Demo/FreeRTOS_Plus_POSIX_with_actor_Windows_Simulator/lib/include/FreeRTOS_POSIX/mqueue.h

   1 /*\r
   2  * Amazon FreeRTOS POSIX V1.1.0\r
   3  * Copyright (C) 2019 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\r
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   6  * this software and associated documentation files (the "Software"), to deal in\r
   7  * the Software without restriction, including without limitation the rights to\r
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
   9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  10  * subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software.\r
  14  *\r
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  21  *\r
  22  * http://aws.amazon.com/freertos\r
  23  * http://www.FreeRTOS.org\r
  24  */\r
  25 \r
  26 /**\r
  27  * @file mqueue.h\r
  28  * @brief Message queues.\r
  29  *\r
  30  * http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/mqueue.h.html\r
  31  */\r
  32 \r
  33 #ifndef _FREERTOS_POSIX_MQUEUE_H_\r
  34 #define _FREERTOS_POSIX_MQUEUE_H_\r
  35 \r
  36 /* FreeRTOS+POSIX includes. */\r
  37 #include "FreeRTOS_POSIX/time.h"\r
  38 \r
  39 /**\r
  40  * @brief Message queue descriptor.\r
  41  */\r
  42 typedef void * mqd_t;\r
  43 \r
  44 /**\r
  45  * @brief Message queue attributes.\r
  46  */\r
  47 struct mq_attr\r
  48 {\r
  49     long mq_flags;   /**< Message queue flags. */\r
  50     long mq_maxmsg;  /**< Maximum number of messages. */\r
  51     long mq_msgsize; /**< Maximum message size. */\r
  52     long mq_curmsgs; /**< Number of messages currently queued. */\r
  53 };\r
  54 \r
  55 /**\r
  56  * @brief Close a message queue.\r
  57  *\r
  58  * http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_close.html\r
  59  *\r
  60  * @retval 0 - Upon successful completion\r
  61  * @retval -1 - A error occurred. errno is also set.\r
  62  *\r
  63  * @sideeffect Possible errno values\r
  64  * <br>\r
  65  * EBADF - The mqdes argument is not a valid message queue descriptor.\r
  66  */\r
  67 int mq_close( mqd_t mqdes );\r
  68 \r
  69 /**\r
  70  * @brief Get message queue attributes.\r
  71  *\r
  72  * http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_getattr.html\r
  73  *\r
  74  * @retval 0 - Upon successful completion\r
  75  * @retval -1 - A error occurred. errno is also set.\r
  76  *\r
  77  * @sideeffect Possible errno values\r
  78  * <br>\r
  79  * DBADF - The mqdes argument is not a valid message queue descriptor.\r
  80  */\r
  81 int mq_getattr( mqd_t mqdes,\r
  82                 struct mq_attr * mqstat );\r
  83 \r
  84 /**\r
  85  * @brief Open a message queue.\r
  86  *\r
  87  * http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_open.html\r
  88  *\r
  89  * @note Supported name pattern: leading &lt;slash&gt; character in name is always required;\r
  90  * the maximum length (excluding null-terminator) of the name argument can be NAME_MAX.\r
  91  * The default value of NAME_MAX in FreeRTOS_POSIX_portable_default.h is 64, which can be\r
  92  * overwritten by user.\r
  93  * @note mode argument is not supported.\r
  94  * @note Supported oflags: O_RDWR, O_CREAT, O_EXCL, and O_NONBLOCK.\r
  95  *\r
  96  * @retval Message queue descriptor -- Upon successful completion\r
  97  * @retval (mqd_t) - 1 -- An error occurred. errno is also set.\r
  98  *\r
  99  * @sideeffect Possible errno values\r
 100  * <br>\r
 101  * EINVAL - name argument is invalid (not following name pattern),\r
 102  * OR if O_CREAT is specified in oflag with attr argument not NULL and either mq_maxmsg or mq_msgsize is equal to or less than zero,\r
 103  * OR either O_CREAT or O_EXCL is not set and a queue with the same name is unlinked but pending to be removed.\r
 104  * <br>\r
 105  * EEXIST - O_CREAT and O_EXCL are set and the named message queue already exists.\r
 106  * <br>\r
 107  * ENOSPC - There is insufficient space for the creation of the new message queue.\r
 108  * <br>\r
 109  * ENOENT - O_CREAT is not set and the named message queue does not exist.\r
 110  */\r
 111 mqd_t mq_open( const char * name,\r
 112                int oflag,\r
 113                mode_t mode,\r
 114                struct mq_attr * attr );\r
 115 \r
 116 /**\r
 117  * @brief Receive a message from a message queue.\r
 118  *\r
 119  * http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_receive.html\r
 120  *\r
 121  * @note msg_prio argument is not supported. Messages are not checked for corruption.\r
 122  *\r
 123  * @retval The length of the selected message in bytes - Upon successful completion.\r
 124  * The message is removed from the queue\r
 125  * @retval -1 - An error occurred. errno is also set.\r
 126  *\r
 127  * @sideeffect Possible errno values\r
 128  * <br>\r
 129  * EBADF - The mqdes argument is not a valid message queue descriptor open for reading.\r
 130  * <br>\r
 131  * EMSGSIZE - The specified message buffer size, msg_len, is less than the message size attribute of the message queue.\r
 132  * <br>\r
 133  * ETIMEDOUT - The O_NONBLOCK flag was not set when the message queue was opened,\r
 134  * but no message arrived on the queue before the specified timeout expired.\r
 135  * <br>\r
 136  * EAGAIN - O_NONBLOCK was set in the message description associated with mqdes, and the specified message queue is empty.\r
 137  */\r
 138 ssize_t mq_receive( mqd_t mqdes,\r
 139                     char * msg_ptr,\r
 140                     size_t msg_len,\r
 141                     unsigned int * msg_prio );\r
 142 \r
 143 /**\r
 144  * @brief Send a message to a message queue.\r
 145  *\r
 146  * http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_send.html\r
 147  *\r
 148  * @note msg_prio argument is not supported.\r
 149  *\r
 150  * @retval 0 - Upon successful completion.\r
 151  * @retval -1 - An error occurred. errno is also set.\r
 152  *\r
 153  * @sideeffect Possible errno values\r
 154  * <br>\r
 155  * EBADF - The mqdes argument is not a valid message queue descriptor open for writing.\r
 156  * <br>\r
 157  * EMSGSIZE - The specified message length, msg_len, exceeds the message size attribute of the message queue,\r
 158  * OR insufficient memory for the message to be sent.\r
 159  * <br>\r
 160  * ETIMEDOUT - The O_NONBLOCK flag was not set when the message queue was opened,\r
 161  * but the timeout expired before the message could be added to the queue.\r
 162  * <br>\r
 163  * EAGAIN - The O_NONBLOCK flag is set in the message queue description associated with mqdes,\r
 164  * and the specified message queue is full.\r
 165  */\r
 166 int mq_send( mqd_t mqdes,\r
 167              const char * msg_ptr,\r
 168              size_t msg_len,\r
 169              unsigned msg_prio );\r
 170 \r
 171 /**\r
 172  * @brief Receive a message from a message queue with timeout.\r
 173  *\r
 174  * http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_timedreceive.html\r
 175  *\r
 176  * @note msg_prio argument is not supported. Messages are not checked for corruption.\r
 177  *\r
 178  * @retval The length of the selected message in bytes - Upon successful completion.\r
 179  * The message is removed from the queue\r
 180  * @retval -1 - An error occurred. errno is also set.\r
 181  *\r
 182  * @sideeffect Possible errno values\r
 183  * <br>\r
 184  * EBADF - The mqdes argument is not a valid message queue descriptor open for reading.\r
 185  * <br>\r
 186  * EMSGSIZE - The specified message buffer size, msg_len, is less than the message size attribute of the message queue.\r
 187  * <br>\r
 188  * EINVAL - The process or thread would have blocked, and the abstime parameter specified a nanoseconds field value\r
 189  * less than zero or greater than or equal to 1000 million.\r
 190  * <br>\r
 191  * ETIMEDOUT - The O_NONBLOCK flag was not set when the message queue was opened,\r
 192  * but no message arrived on the queue before the specified timeout expired.\r
 193  * <br>\r
 194  * EAGAIN - O_NONBLOCK was set in the message description associated with mqdes, and the specified message queue is empty.\r
 195  */\r
 196 ssize_t mq_timedreceive( mqd_t mqdes,\r
 197                          char * msg_ptr,\r
 198                          size_t msg_len,\r
 199                          unsigned * msg_prio,\r
 200                          const struct timespec * abstime );\r
 201 \r
 202 /**\r
 203  * @brief Send a message to a message queue with timeout.\r
 204  *\r
 205  * http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_timedsend.html\r
 206  *\r
 207  * @note msg_prio argument is not supported.\r
 208  *\r
 209  * @retval 0 - Upon successful completion.\r
 210  * @retval -1 - An error occurred. errno is also set.\r
 211  *\r
 212  * @sideeffect Possible errno values\r
 213  * <br>\r
 214  * EBADF - The mqdes argument is not a valid message queue descriptor open for writing.\r
 215  * <br>\r
 216  * EMSGSIZE - The specified message length, msg_len, exceeds the message size attribute of the message queue,\r
 217  * OR insufficient memory for the message to be sent.\r
 218  * <br>\r
 219  * EINVAL - The process or thread would have blocked, and the abstime parameter specified a nanoseconds field\r
 220  * value less than zero or greater than or equal to 1000 million.\r
 221  * <br>\r
 222  * ETIMEDOUT - The O_NONBLOCK flag was not set when the message queue was opened,\r
 223  * but the timeout expired before the message could be added to the queue.\r
 224  * <br>\r
 225  * EAGAIN - The O_NONBLOCK flag is set in the message queue description associated with mqdes,\r
 226  * and the specified message queue is full.\r
 227  */\r
 228 int mq_timedsend( mqd_t mqdes,\r
 229                   const char * msg_ptr,\r
 230                   size_t msg_len,\r
 231                   unsigned msg_prio,\r
 232                   const struct timespec * abstime );\r
 233 \r
 234 /**\r
 235  * @brief Remove a message queue.\r
 236  *\r
 237  * http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_unlink.html\r
 238  *\r
 239  * @retval 0 - Upon successful completion.\r
 240  * @retval -1 - An error occurred. errno is also set.\r
 241  *\r
 242  * @sideeffect Possible errno values\r
 243  * <br>\r
 244  * EINVAL - name argument is invalid. Refer to requirements on name argument in mq_open().\r
 245  * <br>\r
 246  * ENOENT - The named message queue does not exist.\r
 247  */\r
 248 int mq_unlink( const char * name );\r
 249 \r
 250 #endif /* ifndef _FREERTOS_POSIX_MQUEUE_H_ */\r