1MQ_RECEIVE(P)              POSIX Programmer's Manual             MQ_RECEIVE(P)
2
3
4

NAME

6       mq_receive,  mq_timedreceive  -  receive a message from a message queue
7       (REALTIME)
8

SYNOPSIS

10       #include <mqueue.h>
11
12       ssize_t mq_receive(mqd_t mqdes, char *msg_ptr, size_t msg_len,
13              unsigned *msg_prio);
14
15
16
17
18       #include <mqueue.h>
19       #include <time.h>
20       ssize_t mq_timedreceive(mqd_t mqdes, char *restrict msg_ptr,
21              size_t msg_len, unsigned *restrict msg_prio,
22              const struct timespec *restrict abs_timeout);
23
24

DESCRIPTION

26       The mq_receive() function shall receive the oldest of the highest  pri‐
27       ority message(s) from the message queue specified by mqdes. If the size
28       of the buffer in bytes, specified by the msg_len argument, is less than
29       the  mq_msgsize attribute of the message queue, the function shall fail
30       and return an error. Otherwise, the selected message shall  be  removed
31       from the queue and copied to the buffer pointed to by the msg_ptr argu‐
32       ment.
33
34       If the value of msg_len is greater  than  {SSIZE_MAX},  the  result  is
35       implementation-defined.
36
37       If the argument msg_prio is not NULL, the priority of the selected mes‐
38       sage shall be stored in the location referenced by msg_prio.
39
40       If the specified message queue is empty and O_NONBLOCK is  not  set  in
41       the message queue description associated with mqdes, mq_receive() shall
42       block until a message  is  enqueued  on  the  message  queue  or  until
43       mq_receive()  is  interrupted  by  a signal. If more than one thread is
44       waiting to receive a message when a message arrives at an  empty  queue
45       and  the  Priority  Scheduling  option is supported, then the thread of
46       highest priority that has been waiting the longest shall be selected to
47       receive  the message. Otherwise, it is unspecified which waiting thread
48       receives the message. If the  specified  message  queue  is  empty  and
49       O_NONBLOCK  is  set  in  the  message queue description associated with
50       mqdes, no message shall be removed from  the  queue,  and  mq_receive()
51       shall return an error.
52
53       The  mq_timedreceive() function shall receive the oldest of the highest
54       priority  messages  from  the  message  queue  specified  by  mqdes  as
55       described for the mq_receive() function. However, if O_NONBLOCK was not
56       specified when the message queue was opened via the mq_open() function,
57       and no message exists on the queue to satisfy the receive, the wait for
58       such a message shall be terminated when the specified timeout  expires.
59       If O_NONBLOCK is set, this function is equivalent to mq_receive().
60
61       The  timeout  expires  when  the absolute time specified by abs_timeout
62       passes, as measured by the clock on which timeouts are based (that  is,
63       when  the value of that clock equals or exceeds abs_timeout), or if the
64       absolute time specified by abs_timeout has already been passed  at  the
65       time of the call.
66
67       If  the  Timers  option is supported, the timeout shall be based on the
68       CLOCK_REALTIME clock; if the Timers option is not supported, the  time‐
69       out  shall be based on the system clock as returned by the time() func‐
70       tion.
71
72       The resolution of the timeout shall be the resolution of the  clock  on
73       which  it  is  based.  The timespec argument is defined in the <time.h>
74       header.
75
76       Under no circumstance shall the operation fail with a timeout if a mes‐
77       sage  can  be removed from the message queue immediately.  The validity
78       of the abs_timeout parameter need not be checked if a  message  can  be
79       removed from the message queue immediately.
80

RETURN VALUE

82       Upon  successful  completion, the mq_receive()    and mq_timedreceive()
83       functions shall return the length of the selected message in bytes  and
84       the  message  shall  be  removed  from the queue. Otherwise, no message
85       shall be removed from the queue, the functions shall return a value  of
86       -1, and set errno to indicate the error.
87

ERRORS

89       The mq_receive()    and mq_timedreceive() functions shall fail if:
90
91       EAGAIN O_NONBLOCK  was  set  in the message description associated with
92              mqdes, and the specified message queue is empty.
93
94       EBADF  The mqdes argument is not a valid message queue descriptor  open
95              for reading.
96
97       EMSGSIZE
98              The  specified  message  buffer  size, msg_len, is less than the
99              message size attribute of the message queue.
100
101       EINTR  The mq_receive()    or mq_timedreceive()  operation  was  inter‐
102              rupted by a signal.
103
104       EINVAL The  process  or  thread would have blocked, and the abs_timeout
105              parameter specified a nanoseconds field value less than zero  or
106              greater than or equal to 1000 million.
107
108       ETIMEDOUT
109              The  O_NONBLOCK  flag  was  not  set  when the message queue was
110              opened, but no message arrived on the queue before the specified
111              timeout expired.
112
113
114       The mq_receive()    and mq_timedreceive() functions may fail if:
115
116       EBADMSG
117              The  implementation  has detected a data corruption problem with
118              the message.
119
120
121       The following sections are informative.
122

EXAMPLES

124       None.
125

APPLICATION USAGE

127       None.
128

RATIONALE

130       None.
131

FUTURE DIRECTIONS

133       None.
134

SEE ALSO

136       mq_open() , mq_send() , mq_timedsend() , msgctl() , msgget() , msgrcv()
137       ,    msgsnd()   ,   time()   ,   the   Base   Definitions   volume   of
138       IEEE Std 1003.1-2001, <mqueue.h>, <time.h>
139
141       Portions of this text are reprinted and reproduced in  electronic  form
142       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
143       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
144       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
145       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
146       event of any discrepancy between this version and the original IEEE and
147       The Open Group Standard, the original IEEE and The Open Group  Standard
148       is  the  referee document. The original Standard can be obtained online
149       at http://www.opengroup.org/unix/online.html .
150
151
152
153IEEE/The Open Group                  2003                        MQ_RECEIVE(P)
Impressum