\"      $NetBSD: mq_receive.3,v 1.6 2015/11/19 07:03:13 wiz Exp $
\"
\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
\"
Dd November 18, 2015
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 the length of the selected message in bytes, and the
message is removed from the queue.
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
Lk http://www.opengroup.org/unix/online.html .

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.