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.\" $FreeBSD: stable/10/lib/libc/sys/mq_receive.2 208914 2010-06-08 16:48:59Z uqs $
39.\"
40.Dd November 29, 2005
41.Dt MQ_RECEIVE 2
42.Os
43.Sh NAME
44.Nm mq_receive , mq_timedreceive
45.Nd "receive a message from message queue (REALTIME)"
46.Sh LIBRARY
47.Lb librt
48.Sh SYNOPSIS
49.In mqueue.h
50.Ft ssize_t
51.Fo mq_receive
52.Fa "mqd_t mqdes"
53.Fa "char *msg_ptr"
54.Fa "size_t msg_len"
55.Fa "unsigned *msg_prio"
56.Fc
57.Ft ssize_t
58.Fo mq_timedreceive
59.Fa "mqd_t mqdes"
60.Fa "char *msg_ptr"
61.Fa "size_t msg_len"
62.Fa "unsigned *msg_prio"
63.Fa "const struct timespec *abs_timeout"
64.Fc
65.Sh DESCRIPTION
66The
67.Fn mq_receive
68system call receives oldest of the highest priority message(s) from the
69message queue specified by
70.Fa mqdes .
71If the size of the buffer in bytes, specified by the
72.Fa msg_len
73argument, is less than the
74.Va mq_msgsize
75attribute of the message queue, the system call will fail and return an
76error.
77Otherwise, the selected message will be removed from the queue
78and copied to the buffer pointed to by the
79.Fa msg_ptr
80argument.
81.Pp
82If the argument
83.Fa msg_prio
84is not
85.Dv NULL ,
86the priority of the selected message will be stored in the
87location referenced by
88.Fa msg_prio .
89If the specified message queue is empty and
90.Dv O_NONBLOCK
91is not set in the message queue description associated with
92.Fa mqdes ,
93.Fn mq_receive
94will block until a message is enqueued on the message queue or until
95.Fn mq_receive
96is interrupted by a signal.
97If more than one thread is waiting to receive
98a message when a message arrives at an empty queue and the Priority
99Scheduling option is supported, then the thread of highest priority that
100has been waiting the longest will be selected to receive the message.
101Otherwise, it is unspecified which waiting thread receives the message.
102If the specified message queue is empty and
103.Dv O_NONBLOCK
104is set in the message queue description associated with
105.Fa mqdes ,
106no message
107will be removed from the queue, and
108.Fn mq_receive
109will return an error.
110.Pp
111The
112.Fn mq_timedreceive
113system call will receive the oldest of the highest priority messages from the
114message queue specified by
115.Fa mqdes
116as described for the
117.Fn mq_receive
118system call.
119However, if
120.Dv O_NONBLOCK
121was not specified when the message queue was opened via the
122.Fn mq_open
123system call, and no message exists on the queue to satisfy the receive, the wait
124for such a message will be terminated when the specified timeout expires.
125If
126.Dv O_NONBLOCK
127is set, this system call is equivalent to
128.Fn mq_receive .
129.Pp
130The timeout expires when the absolute time specified by
131.Fa abs_timeout
132passes, as measured by the clock on which timeouts are based (that is, when
133the value of that clock equals or exceeds
134.Fa abs_timeout ) ,
135or if the absolute time specified by
136.Fa abs_timeout
137has already been passed at the time of the call.
138.Pp
139The timeout is based on the
140.Dv CLOCK_REALTIME
141clock.
142.Sh RETURN VALUES
143Upon successful completion, the
144.Fn mq_receive
145and
146.Fn mq_timedreceive
147system calls return the length of the selected message in bytes and the
148message is removed from the queue.
149Otherwise, no message is removed
150from the queue, the system call returns a value of \-1,
151and the global variable
152.Va errno
153is set to indicate the error.
154.Sh ERRORS
155The
156.Fn mq_receive
157and
158.Fn mq_timedreceive
159system calls
160will fail if:
161.Bl -tag -width Er
162.It Bq Er EAGAIN
163.Dv O_NONBLOCK
164flag is set in the message queue description associated with
165.Fa mqdes ,
166and the specified message queue is empty.
167.It Bq Er EBADF
168The
169.Fa mqdes
170argument is not a valid message queue descriptor open for reading.
171.It Bq Er EMSGSIZE
172The specified message buffer size,
173.Fa msg_len ,
174is less than the message size attribute of the message queue.
175.It Bq Er EINTR
176The
177.Fn mq_receive
178or
179.Fn mq_timedreceive
180operation was interrupted by a signal.
181.It Bq Er EINVAL
182The process or thread would have blocked, and the
183.Fa abs_timeout
184parameter specified a nanoseconds field value less than zero or greater
185than or equal to 1000 million.
186.It Bq Er ETIMEDOUT
187The
188.Dv O_NONBLOCK
189flag was not set when the message queue was opened, but no message arrived
190on the queue before the specified timeout expired.
191.El
192.Sh SEE ALSO
193.Xr mq_open 2 ,
194.Xr mq_send 2 ,
195.Xr mq_timedsend 2
196.Sh STANDARDS
197The
198.Fn mq_receive
199and
200.Fn mq_timedreceive
201system calls conform to
202.St -p1003.1-2004 .
203.Sh HISTORY
204Support for
205.Tn POSIX
206message queues first appeared in
207.Fx 7.0 .
208.Sh COPYRIGHT
209Portions of this text are reprinted and reproduced in electronic form
210from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
211Portable Operating System Interface (POSIX), The Open Group Base
212Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
213Electrical and Electronics Engineers, Inc and The Open Group.  In the
214event of any discrepancy between this version and the original IEEE and
215The Open Group Standard, the original IEEE and The Open Group Standard is
216the referee document.  The original Standard can be obtained online at
217http://www.opengroup.org/unix/online.html.
218