1.\" $NetBSD: mq_receive.3,v 1.6 2015/11/19 07:03:13 wiz Exp $ 2.\" 3.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 4.\" 5.Dd November 18, 2015 6.Dt MQ_RECEIVE 3 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.In 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 the length of the selected message in bytes, and the 104message is removed from the queue. 105Otherwise, no message will be removed from the queue, 106the functions return a value of 107\-1, and set the global variable 108.Va errno 109to indicate the error. 110.Sh ERRORS 111The 112.Fn mq_receive 113and 114.Fn mq_timedreceive 115functions fail if: 116.Bl -tag -width Er 117.It Bq Er EAGAIN 118.Dv O_NONBLOCK 119was set in the message description associated with 120.Fa mqdes , 121and the specified message queue is empty. 122.It Bq Er EBADF 123The 124.Fa mqdes 125argument is not a valid message queue descriptor open for reading. 126.It Bq Er EINTR 127The 128.Fn mq_receive 129or 130.Fn mq_timedreceive 131operation was interrupted by a signal. 132.It Bq Er EINVAL 133The process or thread would have blocked, and the 134.Fa abs_timeout 135parameter specified a nanoseconds field value less than zero 136or greater than or equal to 1000 million. 137.It Bq Er EMSGSIZE 138The specified message buffer size, 139.Fa msg_len , 140is less than the message size attribute of the message queue. 141.It Bq Er ETIMEDOUT 142The 143.Dv O_NONBLOCK 144flag was not set when the message queue was opened, 145but no message arrived on the queue before the specified timeout expired. 146.El 147.Sh SEE ALSO 148.Xr mq 3 , 149.Xr mq_send 3 150.Sh STANDARDS 151These functions are expected to conform to the 152.St -p1003.1-2001 153standard. 154.Sh HISTORY 155The 156.Fn mq_receive 157and 158.Fn mq_timedreceive 159functions first appeared in 160.Nx 5.0 . 161.Sh COPYRIGHT 162Portions of this text are reprinted and reproduced in electronic form 163from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology 164-- Portable Operating System Interface (POSIX), The Open Group Base 165Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of 166Electrical and Electronics Engineers, Inc and The Open Group. 167In the 168event of any discrepancy between this version and the original IEEE and 169The Open Group Standard, the original IEEE and The Open Group Standard 170is the referee document. 171The original Standard can be obtained online at 172.Lk http://www.opengroup.org/unix/online.html . 173