.\"	$NetBSD: mq_receive.3,v 1.3 2010/06/07 07:21:52 jruoho Exp $
.\"
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
.\"
.Dd June 7, 2010
.Dt MQ_RECEIVE 3
.Os
.Sh NAME
.Nm mq_receive, mq_timedreceive
.Nd receive a message from a message queue (REALTIME)
.Sh LIBRARY
.Lb librt
.Sh SYNOPSIS
.In mqueue.h
.Ft ssize_t
.Fo mq_receive
.Fa "mqd_t mqdes"
.Fa "char *msg_ptr"
.Fa "size_t msg_len"
.Fa "unsigned *msg_prio"
.Fc
.In mqueue.h
.In time.h
.Ft ssize_t
.Fo mq_timedreceive
.Fa "mqd_t mqdes"
.Fa "char *restrict msg_ptr"
.Fa "size_t msg_len"
.Fa "unsigned *restrict msg_prio"
.Fa "const struct timespec *restrict abs_timeout"
.Fc
.Sh DESCRIPTION
The
.Fn mq_receive
function receives the oldest of the highest priority message(s)
from the message queue specified by
.Fa mqdes .
If the size of the buffer in bytes, specified by the
.Fa msg_len
argument, is less than the
.Va mq_msgsize
attribute of the message queue, the function fails and returns an error.
Otherwise, the selected message will be removed from the queue and copied
to the buffer pointed to by the
.Fa msg_ptr
argument.
.Pp
If the argument
.Fa msg_prio
is not
.Dv NULL ,
the priority of the selected message will be stored in the location
referenced by
.Fa msg_prio .
.Pp
If the specified message queue is empty and
.Dv O_NONBLOCK
is not set in the message queue description associated with
.Fa mqdes ,
.Fn mq_receive
blocks until a message is enqueued on the message queue or until
.Fn mq_receive
is interrupted by a signal.
If more than one thread is waiting to receive a message when a
message arrives at an empty queue, then the thread of highest
priority that has been waiting the longest will be selected to
receive the message.
If the specified message queue is empty and
.Dv O_NONBLOCK
is set in the message queue description associated with
.Fa mqdes ,
no message will be removed from the queue, and
.Fn mq_receive
returns an error.
.Pp
The timeout expires when the absolute time specified by
.Fa abs_timeout
passes, as measured by the clock on which timeouts are based (that is,
when the value of that clock equals or exceeds
.Fa abs_timeout ) ,
or if the absolute time specified by
.Fa abs_timeout
has already been passed at the time of the call.
.Pp
The resolution of the timeout is based on the CLOCK_REALTIME clock.
The
.Fa timespec
argument is defined in the
.In time.h
header.
.Pp
Under no circumstance will the operation fail with a timeout if a
message can be removed from the message queue immediately.
The validity of the
.Fa abs_timeout
parameter will not be checked if a message can be removed from the
message queue immediately.
.Sh RETURN VALUES
Upon successful completion, the
.Fn mq_receive
and
.Fn mq_timedreceive
functions return a value of zero.
Otherwise, no message will be removed from the queue,
the functions return a value of
\-1, and set the global variable
.Va errno
to indicate the error.
.Sh ERRORS
The
.Fn mq_receive
and
.Fn mq_timedreceive
functions fail if:
.Bl -tag -width Er
.It Bq Er EAGAIN
.Dv O_NONBLOCK
was set in the message description associated with
.Fa mqdes ,
and the specified message queue is empty.
.It Bq Er EBADF
The
.Fa mqdes
argument is not a valid message queue descriptor open for reading.
.It Bq Er EINTR
The
.Fn mq_receive
or
.Fn mq_timedreceive
operation was interrupted by a signal.
.It Bq Er EINVAL
The process or thread would have blocked, and the
.Fa abs_timeout
parameter specified a nanoseconds field value less than zero
or greater than or equal to 1000 million.
.It Bq Er EMSGSIZE
The specified message buffer size,
.Fa msg_len ,
is less than the message size attribute of the message queue.
.It Bq Er ETIMEDOUT
The
.Dv O_NONBLOCK
flag was not set when the message queue was opened,
but no message arrived on the queue before the specified timeout expired.
.El
.Sh SEE ALSO
.Xr mq 3 ,
.Xr mq_send 3
.Sh STANDARDS
These functions are expected to conform to the
.St -p1003.1-2001
standard.
.Sh HISTORY
The
.Fn mq_receive
and
.Fn mq_timedreceive
functions first appeared in
.Nx 5.0 .
.Sh COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document.
The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .