logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

mq_receive.3p (6277B)


  1. '\" et
  2. .TH MQ_RECEIVE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. mq_receive,
  12. mq_timedreceive
  13. \(em receive a message from a message queue (\fBREALTIME\fP)
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <mqueue.h>
  18. .P
  19. ssize_t mq_receive(mqd_t \fImqdes\fP, char *\fImsg_ptr\fP, size_t \fImsg_len\fP,
  20. unsigned *\fImsg_prio\fP);
  21. .P
  22. #include <mqueue.h>
  23. #include <time.h>
  24. .P
  25. ssize_t mq_timedreceive(mqd_t \fImqdes\fP, char *restrict \fImsg_ptr\fP,
  26. size_t \fImsg_len\fP, unsigned *restrict \fImsg_prio\fP,
  27. const struct timespec *restrict \fIabstime\fP);
  28. .fi
  29. .SH DESCRIPTION
  30. The
  31. \fImq_receive\fR()
  32. function shall receive the oldest of the highest priority
  33. message(s) from the message queue specified by
  34. .IR mqdes .
  35. If the size of the buffer in bytes, specified by the
  36. .IR msg_len
  37. argument, is less than the
  38. .IR mq_msgsize
  39. attribute of the message queue, the function shall fail and return an
  40. error. Otherwise, the selected message shall be removed from the queue
  41. and copied to the buffer pointed to by the
  42. .IR msg_ptr
  43. argument.
  44. .P
  45. If the value of
  46. .IR msg_len
  47. is greater than
  48. {SSIZE_MAX},
  49. the result is implementation-defined.
  50. .P
  51. If the argument
  52. .IR msg_prio
  53. is not NULL, the priority of the selected message shall be stored in the
  54. location referenced by
  55. .IR msg_prio .
  56. .P
  57. If the specified message queue is empty and O_NONBLOCK
  58. is not set in the message queue description associated with
  59. .IR mqdes ,
  60. \fImq_receive\fR()
  61. shall block until a message is enqueued on the message queue or until
  62. \fImq_receive\fR()
  63. is interrupted by a signal. If more than one thread is waiting to
  64. receive a message when a message arrives at an empty queue and the
  65. Priority Scheduling option is supported, then the thread of highest
  66. priority that has been waiting the longest shall be selected to receive
  67. the message. Otherwise, it is unspecified which waiting thread receives
  68. the message. If the specified message queue is empty and O_NONBLOCK is
  69. set in the message queue description associated with
  70. .IR mqdes ,
  71. no message shall be removed from the queue, and
  72. \fImq_receive\fR()
  73. shall return an error.
  74. .P
  75. The
  76. \fImq_timedreceive\fR()
  77. function shall receive the oldest of the highest priority messages
  78. from the message queue specified by
  79. .IR mqdes
  80. as described for the
  81. \fImq_receive\fR()
  82. function. However, if O_NONBLOCK was not specified when the message
  83. queue was opened via the
  84. \fImq_open\fR()
  85. function, and no message exists on the queue to satisfy the receive,
  86. the wait for such a message shall be terminated when the specified
  87. timeout expires. If O_NONBLOCK is set, this function is equivalent to
  88. \fImq_receive\fR().
  89. .P
  90. The timeout expires when the absolute time specified by
  91. .IR abstime
  92. passes, as measured by the clock on which timeouts are based (that is,
  93. when the value of that clock equals or exceeds
  94. .IR abstime ),
  95. or if the absolute time specified by
  96. .IR abstime
  97. has already been passed at the time of the call.
  98. .P
  99. The timeout shall be based on the CLOCK_REALTIME clock.
  100. The resolution of the timeout shall be the resolution of the clock on
  101. which it is based. The
  102. .IR timespec
  103. argument is defined in the
  104. .IR <time.h>
  105. header.
  106. .P
  107. Under no circumstance shall the operation fail with a timeout if a
  108. message can be removed from the message queue immediately. The validity
  109. of the
  110. .IR abstime
  111. parameter need not be checked if a message can be removed from the
  112. message queue immediately.
  113. .SH "RETURN VALUE"
  114. Upon successful completion, the
  115. \fImq_receive\fR()
  116. and
  117. \fImq_timedreceive\fR()
  118. functions shall return the length of the selected message in bytes and
  119. the message shall be removed from the queue. Otherwise, no message
  120. shall be removed from the queue, the functions shall return a value of
  121. \-1, and set
  122. .IR errno
  123. to indicate the error.
  124. .SH ERRORS
  125. These functions shall fail if:
  126. .TP
  127. .BR EAGAIN
  128. O_NONBLOCK was set in the message description associated with
  129. .IR mqdes ,
  130. and the specified message queue is empty.
  131. .TP
  132. .BR EBADF
  133. The
  134. .IR mqdes
  135. argument is not a valid message queue descriptor open for reading.
  136. .TP
  137. .BR EMSGSIZE
  138. The specified message buffer size,
  139. .IR msg_len ,
  140. is less than the message size attribute of the message queue.
  141. .TP
  142. .BR EINTR
  143. The
  144. \fImq_receive\fR()
  145. or
  146. \fImq_timedreceive\fR()
  147. operation was interrupted by a signal.
  148. .TP
  149. .BR EINVAL
  150. The process or thread would have blocked, and the
  151. .IR abstime
  152. parameter specified a nanoseconds field value less than zero or greater
  153. than or equal to 1\|000 million.
  154. .TP
  155. .BR ETIMEDOUT
  156. The O_NONBLOCK flag was not set when the message queue was opened, but
  157. no message arrived on the queue before the specified timeout expired.
  158. .P
  159. These functions may fail if:
  160. .TP
  161. .BR EBADMSG
  162. The implementation has detected a data corruption problem with the
  163. message.
  164. .LP
  165. .IR "The following sections are informative."
  166. .SH EXAMPLES
  167. None.
  168. .SH "APPLICATION USAGE"
  169. None.
  170. .SH RATIONALE
  171. None.
  172. .SH "FUTURE DIRECTIONS"
  173. None.
  174. .SH "SEE ALSO"
  175. .IR "\fImq_open\fR\^(\|)",
  176. .IR "\fImq_send\fR\^(\|)",
  177. .IR "\fImsgctl\fR\^(\|)",
  178. .IR "\fImsgget\fR\^(\|)",
  179. .IR "\fImsgrcv\fR\^(\|)",
  180. .IR "\fImsgsnd\fR\^(\|)",
  181. .IR "\fItime\fR\^(\|)"
  182. .P
  183. The Base Definitions volume of POSIX.1\(hy2017,
  184. .IR "\fB<mqueue.h>\fP",
  185. .IR "\fB<time.h>\fP"
  186. .\"
  187. .SH COPYRIGHT
  188. Portions of this text are reprinted and reproduced in electronic form
  189. from IEEE Std 1003.1-2017, Standard for Information Technology
  190. -- Portable Operating System Interface (POSIX), The Open Group Base
  191. Specifications Issue 7, 2018 Edition,
  192. Copyright (C) 2018 by the Institute of
  193. Electrical and Electronics Engineers, Inc and The Open Group.
  194. In the event of any discrepancy between this version and the original IEEE and
  195. The Open Group Standard, the original IEEE and The Open Group Standard
  196. is the referee document. The original Standard can be obtained online at
  197. http://www.opengroup.org/unix/online.html .
  198. .PP
  199. Any typographical or formatting errors that appear
  200. in this page are most likely
  201. to have been introduced during the conversion of the source files to
  202. man page format. To report such errors, see
  203. https://www.kernel.org/doc/man-pages/reporting_bugs.html .