1.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice(s), this list of conditions and the following disclaimer as 9.\" the first lines of this file unmodified other than the possible 10.\" addition of one or more copyright notices. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice(s), this list of conditions and the following disclaimer in 13.\" the documentation and/or other materials provided with the 14.\" distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 17.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 19.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE 20.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 23.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 24.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 25.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 26.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.\" Portions of this text are reprinted and reproduced in electronic form 29.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- 30.\" Portable Operating System Interface (POSIX), The Open Group Base 31.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of 32.\" Electrical and Electronics Engineers, Inc and The Open Group. In the 33.\" event of any discrepancy between this version and the original IEEE and 34.\" The Open Group Standard, the original IEEE and The Open Group Standard is 35.\" the referee document. The original Standard can be obtained online at 36.\" http://www.opengroup.org/unix/online.html. 37.\" 38.Dd November 29, 2005 39.Dt MQ_RECEIVE 2 40.Os 41.Sh NAME 42.Nm mq_receive , mq_timedreceive 43.Nd "receive a message from message queue (REALTIME)" 44.Sh LIBRARY 45.Lb librt 46.Sh SYNOPSIS 47.In mqueue.h 48.Ft ssize_t 49.Fo mq_receive 50.Fa "mqd_t mqdes" 51.Fa "char *msg_ptr" 52.Fa "size_t msg_len" 53.Fa "unsigned *msg_prio" 54.Fc 55.Ft ssize_t 56.Fo mq_timedreceive 57.Fa "mqd_t mqdes" 58.Fa "char *msg_ptr" 59.Fa "size_t msg_len" 60.Fa "unsigned *msg_prio" 61.Fa "const struct timespec *abs_timeout" 62.Fc 63.Sh DESCRIPTION 64The 65.Fn mq_receive 66system call receives oldest of the highest priority message(s) from the 67message queue specified by 68.Fa mqdes . 69If the size of the buffer in bytes, specified by the 70.Fa msg_len 71argument, is less than the 72.Va mq_msgsize 73attribute of the message queue, the system call will fail and return an 74error. 75Otherwise, the selected message will be removed from the queue 76and copied to the buffer pointed to by the 77.Fa msg_ptr 78argument. 79.Pp 80If the argument 81.Fa msg_prio 82is not 83.Dv NULL , 84the priority of the selected message will be stored in the 85location referenced by 86.Fa msg_prio . 87If the specified message queue is empty and 88.Dv O_NONBLOCK 89is not set in the message queue description associated with 90.Fa mqdes , 91.Fn mq_receive 92will block until a message is enqueued on the message queue or until 93.Fn mq_receive 94is interrupted by a signal. 95If more than one thread is waiting to receive 96a message when a message arrives at an empty queue and the Priority 97Scheduling option is supported, then the thread of highest priority that 98has been waiting the longest will be selected to receive the message. 99Otherwise, it is unspecified which waiting thread receives the message. 100If the specified message queue is empty and 101.Dv O_NONBLOCK 102is set in the message queue description associated with 103.Fa mqdes , 104no message 105will be removed from the queue, and 106.Fn mq_receive 107will return an error. 108.Pp 109The 110.Fn mq_timedreceive 111system call will receive the oldest of the highest priority messages from the 112message queue specified by 113.Fa mqdes 114as described for the 115.Fn mq_receive 116system call. 117However, if 118.Dv O_NONBLOCK 119was not specified when the message queue was opened via the 120.Fn mq_open 121system call, and no message exists on the queue to satisfy the receive, the wait 122for such a message will be terminated when the specified timeout expires. 123If 124.Dv O_NONBLOCK 125is set, this system call is equivalent to 126.Fn mq_receive . 127.Pp 128The timeout expires when the absolute time specified by 129.Fa abs_timeout 130passes, as measured by the clock on which timeouts are based (that is, when 131the value of that clock equals or exceeds 132.Fa abs_timeout ) , 133or if the absolute time specified by 134.Fa abs_timeout 135has already been passed at the time of the call. 136.Pp 137The timeout is based on the 138.Dv CLOCK_REALTIME 139clock. 140.Sh RETURN VALUES 141Upon successful completion, the 142.Fn mq_receive 143and 144.Fn mq_timedreceive 145system calls return the length of the selected message in bytes and the 146message is removed from the queue. 147Otherwise, no message is removed 148from the queue, the system call returns a value of \-1, 149and the global variable 150.Va errno 151is set to indicate the error. 152.Sh ERRORS 153The 154.Fn mq_receive 155and 156.Fn mq_timedreceive 157system calls 158will fail if: 159.Bl -tag -width Er 160.It Bq Er EAGAIN 161.Dv O_NONBLOCK 162flag is set in the message queue description associated with 163.Fa mqdes , 164and the specified message queue is empty. 165.It Bq Er EBADF 166The 167.Fa mqdes 168argument is not a valid message queue descriptor open for reading. 169.It Bq Er EMSGSIZE 170The specified message buffer size, 171.Fa msg_len , 172is less than the message size attribute of the message queue. 173.It Bq Er EINTR 174The 175.Fn mq_receive 176or 177.Fn mq_timedreceive 178operation was interrupted by a signal. 179.It Bq Er EINVAL 180The process or thread would have blocked, and the 181.Fa abs_timeout 182parameter specified a nanoseconds field value less than zero or greater 183than or equal to 1000 million. 184.It Bq Er ETIMEDOUT 185The 186.Dv O_NONBLOCK 187flag was not set when the message queue was opened, but no message arrived 188on the queue before the specified timeout expired. 189.El 190.Sh SEE ALSO 191.Xr mq_open 2 , 192.Xr mq_send 2 , 193.Xr mq_timedsend 2 194.Sh STANDARDS 195The 196.Fn mq_receive 197and 198.Fn mq_timedreceive 199system calls conform to 200.St -p1003.1-2004 . 201.Sh HISTORY 202Support for 203.Tn POSIX 204message queues first appeared in 205.Fx 7.0 . 206.Sh COPYRIGHT 207Portions of this text are reprinted and reproduced in electronic form 208from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- 209Portable Operating System Interface (POSIX), The Open Group Base 210Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of 211Electrical and Electronics Engineers, Inc and The Open Group. In the 212event of any discrepancy between this version and the original IEEE and 213The Open Group Standard, the original IEEE and The Open Group Standard is 214the referee document. The original Standard can be obtained online at 215http://www.opengroup.org/unix/online.html. 216