]>
Commit | Line | Data |
---|---|---|
c11b1abf | 1 | .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
80a99f39 | 2 | .\" |
5fbde956 | 3 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
80a99f39 | 4 | .\" |
4c1c5274 | 5 | .TH mq_receive 3 (date) "Linux man-pages (unreleased)" |
80a99f39 MK |
6 | .SH NAME |
7 | mq_receive, mq_timedreceive \- receive a message from a message queue | |
39914dce AC |
8 | .SH LIBRARY |
9 | Real-time library | |
8fc3b2cf | 10 | .RI ( librt ", " \-lrt ) |
80a99f39 MK |
11 | .SH SYNOPSIS |
12 | .nf | |
13 | .B #include <mqueue.h> | |
68e4db0a | 14 | .PP |
36e212c6 | 15 | .BI "ssize_t mq_receive(mqd_t " mqdes ", char *" msg_ptr , |
c1234a3b | 16 | .BI " size_t " msg_len ", unsigned int *" msg_prio ); |
68e4db0a | 17 | .PP |
80a99f39 MK |
18 | .B #include <time.h> |
19 | .B #include <mqueue.h> | |
68e4db0a | 20 | .PP |
6d512409 AC |
21 | .BI "ssize_t mq_timedreceive(mqd_t " mqdes ", char *restrict " msg_ptr , |
22 | .BI " size_t " msg_len ", unsigned int *restrict " msg_prio , | |
23 | .BI " const struct timespec *restrict " abs_timeout ); | |
80a99f39 | 24 | .fi |
68e4db0a | 25 | .PP |
9a30939e | 26 | .ad l |
d39ad78f | 27 | .RS -4 |
9a30939e MK |
28 | Feature Test Macro Requirements for glibc (see |
29 | .BR feature_test_macros (7)): | |
d39ad78f | 30 | .RE |
68e4db0a | 31 | .PP |
9a30939e | 32 | .BR mq_timedreceive (): |
9d2adbae | 33 | .nf |
5c10d2c5 | 34 | _POSIX_C_SOURCE >= 200112L |
9d2adbae | 35 | .fi |
80a99f39 MK |
36 | .SH DESCRIPTION |
37 | .BR mq_receive () | |
c13182ef | 38 | removes the oldest message with the highest priority from |
d9cb0d7d | 39 | the message queue referred to by the message queue descriptor |
80a99f39 MK |
40 | .IR mqdes , |
41 | and places it in the buffer pointed to by | |
42 | .IR msg_ptr . | |
43 | The | |
44 | .I msg_len | |
45 | argument specifies the size of the buffer pointed to by | |
46 | .IR msg_ptr ; | |
61a70efc | 47 | this must be greater than or equal to the |
80a99f39 | 48 | .I mq_msgsize |
c13182ef | 49 | attribute of the queue (see |
80a99f39 MK |
50 | .BR mq_getattr (3)). |
51 | If | |
37f02e32 | 52 | .I msg_prio |
c13182ef | 53 | is not NULL, then the buffer to which it points is used |
80a99f39 | 54 | to return the priority associated with the received message. |
847e0d88 | 55 | .PP |
80a99f39 MK |
56 | If the queue is empty, then, by default, |
57 | .BR mq_receive () | |
58 | blocks until a message becomes available, | |
59 | or the call is interrupted by a signal handler. | |
c13182ef | 60 | If the |
80a99f39 MK |
61 | .B O_NONBLOCK |
62 | flag is enabled for the message queue description, | |
63 | then the call instead fails immediately with the error | |
64 | .BR EAGAIN . | |
847e0d88 | 65 | .PP |
80a99f39 MK |
66 | .BR mq_timedreceive () |
67 | behaves just like | |
68 | .BR mq_receive (), | |
69 | except that if the queue is empty and the | |
70 | .B O_NONBLOCK | |
71 | flag is not enabled for the message queue description, then | |
72 | .I abs_timeout | |
3824cf5b MK |
73 | points to a structure which specifies how long the call will block. |
74 | This value is an absolute timeout in seconds and nanoseconds | |
75 | since the Epoch, 1970-01-01 00:00:00 +0000 (UTC), | |
e97e048a | 76 | specified in a |
77 | .BR timespec (3) | |
78 | structure. | |
bdd915e2 | 79 | .PP |
80a99f39 MK |
80 | If no message is available, |
81 | and the timeout has already expired by the time of the call, | |
82 | .BR mq_timedreceive () | |
83 | returns immediately. | |
84 | .SH RETURN VALUE | |
85 | On success, | |
86 | .BR mq_receive () | |
87 | and | |
88 | .BR mq_timedreceive () | |
89 | return the number of bytes in the received message; | |
90 | on error, \-1 is returned, with | |
c13182ef | 91 | .I errno |
80a99f39 MK |
92 | set to indicate the error. |
93 | .SH ERRORS | |
94 | .TP | |
95 | .B EAGAIN | |
96 | The queue was empty, and the | |
97 | .B O_NONBLOCK | |
98 | flag was set for the message queue description referred to by | |
99 | .IR mqdes . | |
100 | .TP | |
101 | .B EBADF | |
e186d0ca | 102 | The descriptor specified in |
80a99f39 | 103 | .I mqdes |
e1ca8255 | 104 | was invalid or not opened for reading. |
80a99f39 | 105 | .TP |
80a99f39 | 106 | .B EINTR |
01538d0d MK |
107 | The call was interrupted by a signal handler; see |
108 | .BR signal (7). | |
80a99f39 MK |
109 | .TP |
110 | .B EINVAL | |
c13182ef | 111 | The call would have blocked, and |
80a99f39 MK |
112 | .I abs_timeout |
113 | was invalid, either because | |
114 | .I tv_sec | |
115 | was less than zero, or because | |
c13182ef | 116 | .I tv_nsec |
80a99f39 MK |
117 | was less than zero or greater than 1000 million. |
118 | .TP | |
eab64696 | 119 | .B EMSGSIZE |
0daa9e92 | 120 | .I msg_len |
eab64696 MK |
121 | was less than the |
122 | .I mq_msgsize | |
123 | attribute of the message queue. | |
124 | .TP | |
80a99f39 MK |
125 | .B ETIMEDOUT |
126 | The call timed out before a message could be transferred. | |
db17fccd | 127 | .SH ATTRIBUTES |
dd975639 PH |
128 | For an explanation of the terms used in this section, see |
129 | .BR attributes (7). | |
c466875e MK |
130 | .ad l |
131 | .nh | |
dd975639 PH |
132 | .TS |
133 | allbox; | |
c466875e | 134 | lbx lb lb |
dd975639 PH |
135 | l l l. |
136 | Interface Attribute Value | |
137 | T{ | |
138 | .BR mq_receive (), | |
db17fccd | 139 | .BR mq_timedreceive () |
dd975639 PH |
140 | T} Thread safety MT-Safe |
141 | .TE | |
c466875e MK |
142 | .hy |
143 | .ad | |
144 | .sp 1 | |
3113c7f3 | 145 | .SH STANDARDS |
8096c228 | 146 | POSIX.1-2001, POSIX.1-2008. |
c89e428b MK |
147 | .SH NOTES |
148 | On Linux, | |
149 | .BR mq_timedreceive () | |
150 | is a system call, and | |
151 | .BR mq_receive () | |
152 | is a library function layered on top of that system call. | |
47297adb | 153 | .SH SEE ALSO |
80a99f39 MK |
154 | .BR mq_close (3), |
155 | .BR mq_getattr (3), | |
156 | .BR mq_notify (3), | |
157 | .BR mq_open (3), | |
158 | .BR mq_send (3), | |
159 | .BR mq_unlink (3), | |
e97e048a | 160 | .BR timespec (3), |
1d7c4d16 MK |
161 | .BR mq_overview (7), |
162 | .BR time (7) |