1.\" $NetBSD: mq_receive.3,v 1.1 2009/01/05 21:19:49 rmind Exp $ 2.\" 3.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 4.\" 5.Dd August 19, 2009 6.Dt MQ_RECEIVE 2 7.Os 8.Sh NAME 9.Nm mq_receive , mq_timedreceive 10.Nd receive a message from a message queue (REALTIME) 11.Sh LIBRARY 12.Lb librt 13.Sh SYNOPSIS 14.In mqueue.h 15.Ft ssize_t 16.Fo mq_receive 17.Fa "mqd_t mqdes" 18.Fa "char *msg_ptr" 19.Fa "size_t msg_len" 20.Fa "unsigned *msg_prio" 21.Fc 22.In mqueue.h 23.In time.h 24.Ft ssize_t 25.Fo mq_timedreceive 26.Fa "mqd_t mqdes" 27.Fa "char *restrict msg_ptr" 28.Fa "size_t msg_len" 29.Fa "unsigned *restrict msg_prio" 30.Fa "const struct timespec *restrict abs_timeout" 31.Fc 32.Sh DESCRIPTION 33The 34.Fn mq_receive 35function receives the oldest of the highest priority message(s) 36from the message queue specified by 37.Fa mqdes . 38If the size of the buffer in bytes, specified by the 39.Fa msg_len 40argument, is less than the 41.Va mq_msgsize 42attribute of the message queue, the function fails and returns an error. 43Otherwise, the selected message will be removed from the queue and copied 44to the buffer pointed to by the 45.Fa msg_ptr 46argument. 47.Pp 48If the argument 49.Fa msg_prio 50is not 51.Dv NULL , 52the priority of the selected message will be stored in the location 53referenced by 54.Fa msg_prio . 55.Pp 56If the specified message queue is empty and 57.Dv O_NONBLOCK 58is not set in the message queue description associated with 59.Fa mqdes , 60.Fn mq_receive 61blocks until a message is enqueued on the message queue or until 62.Fn mq_receive 63is interrupted by a signal. 64If more than one thread is waiting to receive a message when a 65message arrives at an empty queue, then the thread of highest 66priority that has been waiting the longest will be selected to 67receive the message. 68If the specified message queue is empty and 69.Dv O_NONBLOCK 70is set in the message queue description associated with 71.Fa mqdes , 72no message will be removed from the queue, and 73.Fn mq_receive 74returns an error. 75.Pp 76The timeout expires when the absolute time specified by 77.Fa abs_timeout 78passes, as measured by the clock on which timeouts are based (that is, 79when the value of that clock equals or exceeds 80.Fa abs_timeout ) , 81or if the absolute time specified by 82.Fa abs_timeout 83has already been passed at the time of the call. 84.Pp 85The resolution of the timeout is based on the CLOCK_REALTIME clock. 86The 87.Fa timespec 88argument is defined in the 89.Aq time.h 90header. 91.Pp 92Under no circumstance will the operation fail with a timeout if a 93message can be removed from the message queue immediately. 94The validity of the 95.Fa abs_timeout 96parameter will not be checked if a message can be removed from the 97message queue immediately. 98.Sh RETURN VALUES 99Upon successful completion, the 100.Fn mq_receive 101and 102.Fn mq_timedreceive 103functions return a value of zero. 104Otherwise, no message will be removed from the queue, 105the functions return a value of 106\-1, and set the global variable 107.Va errno 108to indicate the error. 109.Sh ERRORS 110The 111.Fn mq_receive 112and 113.Fn mq_timedreceive 114functions fail if: 115.Bl -tag -width Er 116.It Bq Er EAGAIN 117.Dv O_NONBLOCK 118was set in the message description associated with 119.Fa mqdes , 120and the specified message queue is empty. 121.It Bq Er EBADF 122The 123.Fa mqdes 124argument is not a valid message queue descriptor open for reading. 125.It Bq Er EINTR 126The 127.Fn mq_receive 128or 129.Fn mq_timedreceive 130operation was interrupted by a signal. 131.It Bq Er EINVAL 132The process or thread would have blocked, and the 133.Fa abs_timeout 134parameter specified a nanoseconds field value less than zero 135or greater than or equal to 1000 million. 136.It Bq Er EMSGSIZE 137The specified message buffer size, 138.Fa msg_len , 139is less than the message size attribute of the message queue. 140.It Bq Er ETIMEDOUT 141The 142.Dv O_NONBLOCK 143flag was not set when the message queue was opened, 144but no message arrived on the queue before the specified timeout expired. 145.El 146.Sh SEE ALSO 147.Xr mq_close 2 , 148.Xr mq_getattr 2 , 149.Xr mq_notify 2 , 150.Xr mq_open 2 , 151.Xr mq_send 2 , 152.Xr mq_setattr 2 , 153.Xr mq_unlink 2 154.Sh STANDARDS 155These functions are expected to conform to the 156.St -p1003.1-2001 157standard. 158.Sh HISTORY 159The 160.Fn mq_receive 161and 162.Fn mq_timedreceive 163functions first appeared in 164.Dx 2.5 . 165.Sh COPYRIGHT 166Portions of this text are reprinted and reproduced in electronic form 167from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology 168-- Portable Operating System Interface (POSIX), The Open Group Base 169Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of 170Electrical and Electronics Engineers, Inc and The Open Group. 171In the 172event of any discrepancy between this version and the original IEEE and 173The Open Group Standard, the original IEEE and The Open Group Standard 174is the referee document. 175The original Standard can be obtained online at 176http://www.opengroup.org/unix/online.html . 177