]>
Commit | Line | Data |
---|---|---|
80a99f39 | 1 | '\" t |
c11b1abf | 2 | .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
80a99f39 | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
80a99f39 MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
80a99f39 MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
10d76543 MK |
17 | .\" the use of the information contained herein. The author(s) may not |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
80a99f39 MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
80a99f39 | 25 | .\" |
4b8c67d9 | 26 | .TH MQ_NOTIFY 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
80a99f39 MK |
27 | .SH NAME |
28 | mq_notify \- register for notification when a message is available | |
29 | .SH SYNOPSIS | |
30 | .nf | |
31 | .B #include <mqueue.h> | |
68e4db0a | 32 | .PP |
0d5f6a62 | 33 | .BI "int mq_notify(mqd_t " mqdes ", const struct sigevent *" sevp ); |
80a99f39 | 34 | .fi |
68e4db0a | 35 | .PP |
1b2d3fca | 36 | Link with \fI\-lrt\fP. |
80a99f39 MK |
37 | .SH DESCRIPTION |
38 | .BR mq_notify () | |
c13182ef MK |
39 | allows the calling process to register or unregister for delivery of |
40 | an asynchronous notification when a new message arrives on | |
d9cb0d7d | 41 | the empty message queue referred to by the message queue descriptor |
80a99f39 | 42 | .IR mqdes . |
847e0d88 | 43 | .PP |
c13182ef | 44 | The |
0d5f6a62 | 45 | .I sevp |
c13182ef | 46 | argument is a pointer to a |
80a99f39 | 47 | .I sigevent |
168e3472 MK |
48 | structure. |
49 | For the definition and general details of this structure, see | |
50 | .BR sigevent (7). | |
08140a81 | 51 | .PP |
c13182ef | 52 | If |
0d5f6a62 | 53 | .I sevp |
b437fdd9 | 54 | is a non-null pointer, then |
80a99f39 MK |
55 | .BR mq_notify () |
56 | registers the calling process to receive message notification. | |
c13182ef MK |
57 | The |
58 | .I sigev_notify | |
80a99f39 MK |
59 | field of the |
60 | .I sigevent | |
168e3472 | 61 | structure to which |
0d5f6a62 | 62 | .I sevp |
80a99f39 MK |
63 | points specifies how notification is to be performed. |
64 | This field has one of the following values: | |
65 | .TP | |
66 | .B SIGEV_NONE | |
c13182ef | 67 | A "null" notification: the calling process is registered as the target |
80a99f39 MK |
68 | for notification, but when a message arrives, no notification is sent. |
69 | .\" When is SIGEV_NONE useful? | |
70 | .TP | |
71 | .B SIGEV_SIGNAL | |
72 | Notify the process by sending the signal specified in | |
7cd24403 | 73 | .IR sigev_signo . |
168e3472 MK |
74 | See |
75 | .BR sigevent (7) | |
76 | for general details. | |
77 | The | |
80a99f39 | 78 | .I si_code |
168e3472 MK |
79 | field of the |
80 | .I siginfo_t | |
81 | structure will be set to | |
82 | .BR SI_MESGQ . | |
83 | In addition, | |
80a99f39 MK |
84 | .\" I don't know of other implementations that set |
85 | .\" si_pid and si_uid -- MTK | |
86 | .I si_pid | |
168e3472 | 87 | will be set to the PID of the process that sent the message, and |
80a99f39 | 88 | .I si_uid |
168e3472 | 89 | will be set to the real user ID of the sending process. |
80a99f39 MK |
90 | .TP |
91 | .B SIGEV_THREAD | |
168e3472 MK |
92 | Upon message delivery, invoke |
93 | .I sigev_notify_function | |
94 | as if it were the start function of a new thread. | |
95 | See | |
96 | .BR sigevent (7) | |
97 | for details. | |
80a99f39 MK |
98 | .PP |
99 | Only one process can be registered to receive notification | |
100 | from a message queue. | |
847e0d88 | 101 | .PP |
c13182ef | 102 | If |
0d5f6a62 | 103 | .I sevp |
80a99f39 MK |
104 | is NULL, and the calling process is currently registered to receive |
105 | notifications for this message queue, then the registration is removed; | |
c13182ef | 106 | another process can then register to receive a message notification |
80a99f39 | 107 | for this queue. |
847e0d88 | 108 | .PP |
33a0ccb2 | 109 | Message notification occurs only when a new message arrives and |
80a99f39 MK |
110 | the queue was previously empty. |
111 | If the queue was not empty at the time | |
112 | .BR mq_notify () | |
33a0ccb2 | 113 | was called, then a notification will occur only after |
80a99f39 | 114 | the queue is emptied and a new message arrives. |
847e0d88 | 115 | .PP |
80a99f39 MK |
116 | If another process or thread is waiting to read a message |
117 | from an empty queue using | |
fb186734 | 118 | .BR mq_receive (3), |
c13182ef | 119 | then any message notification registration is ignored: |
80a99f39 | 120 | the message is delivered to the process or thread calling |
fb186734 | 121 | .BR mq_receive (3), |
80a99f39 | 122 | and the message notification registration remains in effect. |
847e0d88 | 123 | .PP |
c13182ef MK |
124 | Notification occurs once: after a notification is delivered, |
125 | the notification registration is removed, | |
80a99f39 MK |
126 | and another process can register for message notification. |
127 | If the notified process wishes to receive the next notification, | |
c13182ef | 128 | it can use |
80a99f39 MK |
129 | .BR mq_notify () |
130 | to request a further notification. | |
131 | This should be done before emptying all unread messages from the queue. | |
ff40dbb3 | 132 | (Placing the queue in nonblocking mode is useful for emptying |
80a99f39 MK |
133 | the queue of messages without blocking once it is empty.) |
134 | .SH RETURN VALUE | |
135 | On success | |
136 | .BR mq_notify () | |
137 | returns 0; on error, \-1 is returned, with | |
c13182ef | 138 | .I errno |
80a99f39 MK |
139 | set to indicate the error. |
140 | .SH ERRORS | |
141 | .TP | |
142 | .B EBADF | |
d9cb0d7d | 143 | The message queue descriptor specified in |
80a99f39 MK |
144 | .I mqdes |
145 | is invalid. | |
146 | .TP | |
147 | .B EBUSY | |
148 | Another process has already registered to receive notification | |
149 | for this message queue. | |
150 | .TP | |
151 | .B EINVAL | |
0d5f6a62 | 152 | .I sevp\->sigev_notify |
80a99f39 | 153 | is not one of the permitted values; or |
0d5f6a62 | 154 | .I sevp\->sigev_notify |
c13182ef MK |
155 | is |
156 | .B SIGEV_SIGNAL | |
157 | and | |
0d5f6a62 | 158 | .I sevp\->sigev_signo |
1954b6a9 | 159 | is not a valid signal number. |
80a99f39 MK |
160 | .TP |
161 | .B ENOMEM | |
162 | Insufficient memory. | |
8ea4ea95 MK |
163 | .PP |
164 | POSIX.1-2008 says that an implementation | |
165 | .I may | |
166 | generate an | |
167 | .B EINVAL | |
168 | .\" Linux does not do this | |
169 | error if | |
0d5f6a62 | 170 | .I sevp |
8ea4ea95 MK |
171 | is NULL, and the caller is not currently registered to receive |
172 | notifications for the queue | |
173 | .IR mqdes . | |
3964d56d ZL |
174 | .SH ATTRIBUTES |
175 | For an explanation of the terms used in this section, see | |
176 | .BR attributes (7). | |
177 | .TS | |
178 | allbox; | |
179 | lb lb lb | |
180 | l l l. | |
181 | Interface Attribute Value | |
182 | T{ | |
183 | .BR mq_notify () | |
184 | T} Thread safety MT-Safe | |
185 | .TE | |
847e0d88 | 186 | .sp 1 |
80a99f39 MK |
187 | .SH CONFORMING TO |
188 | POSIX.1-2001. | |
c5aee027 MK |
189 | .SH NOTES |
190 | .\" | |
0722a578 | 191 | .SS C library/kernel differences |
c5aee027 MK |
192 | In the glibc implementation, the |
193 | .BR mq_notify () | |
194 | library function is implemented on top of the system call of the same name. | |
195 | When | |
196 | .I sevp | |
197 | is NULL, or specifies a notification mechanism other than | |
198 | .BR SIGEV_THREAD , | |
199 | the library function directly invokes the system call. | |
200 | For | |
201 | .BR SIGEV_THREAD , | |
202 | much of the implementation resides within the library, | |
203 | rather than the kernel. | |
204 | (This is necessarily so, | |
205 | since the thread involved in handling the notification is one | |
206 | that must be managed by the C library POSIX threads implementation.) | |
207 | The implementation involves the use of a raw | |
208 | .BR netlink (7) | |
209 | socket and creates a new thread for each notification that is | |
210 | delivered to the process. | |
80a99f39 MK |
211 | .SH EXAMPLE |
212 | The following program registers a notification request for the | |
213 | message queue named in its command-line argument. | |
214 | Notification is performed by creating a thread. | |
c13182ef | 215 | The thread executes a function which reads one message from the |
80a99f39 | 216 | queue and then terminates the process. |
f30b7415 | 217 | .SS Program source |
e7d0bb47 | 218 | .EX |
80a99f39 MK |
219 | #include <pthread.h> |
220 | #include <mqueue.h> | |
80a99f39 MK |
221 | #include <stdio.h> |
222 | #include <stdlib.h> | |
223 | #include <unistd.h> | |
224 | ||
6a578b88 MK |
225 | #define handle_error(msg) \\ |
226 | do { perror(msg); exit(EXIT_FAILURE); } while (0) | |
80a99f39 MK |
227 | |
228 | static void /* Thread start function */ | |
229 | tfunc(union sigval sv) | |
230 | { | |
231 | struct mq_attr attr; | |
232 | ssize_t nr; | |
233 | void *buf; | |
234 | mqd_t mqdes = *((mqd_t *) sv.sival_ptr); | |
235 | ||
236 | /* Determine max. msg size; allocate buffer to receive msg */ | |
237 | ||
29059a65 | 238 | if (mq_getattr(mqdes, &attr) == \-1) |
6a578b88 | 239 | handle_error("mq_getattr"); |
80a99f39 | 240 | buf = malloc(attr.mq_msgsize); |
29059a65 | 241 | if (buf == NULL) |
6a578b88 | 242 | handle_error("malloc"); |
80a99f39 MK |
243 | |
244 | nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL); | |
29059a65 | 245 | if (nr == \-1) |
6a578b88 | 246 | handle_error("mq_receive"); |
80a99f39 | 247 | |
8c5fcd21 | 248 | printf("Read %zd bytes from MQ\\n", nr); |
80a99f39 MK |
249 | free(buf); |
250 | exit(EXIT_SUCCESS); /* Terminate the process */ | |
251 | } | |
252 | ||
253 | int | |
254 | main(int argc, char *argv[]) | |
255 | { | |
256 | mqd_t mqdes; | |
0d5f6a62 | 257 | struct sigevent sev; |
80a99f39 | 258 | |
6b34fb3f | 259 | if (argc != 2) { |
5a6194a4 MK |
260 | fprintf(stderr, "Usage: %s <mq\-name>\\n", argv[0]); |
261 | exit(EXIT_FAILURE); | |
6b34fb3f | 262 | } |
80a99f39 MK |
263 | |
264 | mqdes = mq_open(argv[1], O_RDONLY); | |
29059a65 | 265 | if (mqdes == (mqd_t) \-1) |
6a578b88 | 266 | handle_error("mq_open"); |
80a99f39 | 267 | |
0d5f6a62 MK |
268 | sev.sigev_notify = SIGEV_THREAD; |
269 | sev.sigev_notify_function = tfunc; | |
270 | sev.sigev_notify_attributes = NULL; | |
271 | sev.sigev_value.sival_ptr = &mqdes; /* Arg. to thread func. */ | |
272 | if (mq_notify(mqdes, &sev) == \-1) | |
6a578b88 | 273 | handle_error("mq_notify"); |
80a99f39 MK |
274 | |
275 | pause(); /* Process will be terminated by thread function */ | |
276 | } | |
e7d0bb47 | 277 | .EE |
47297adb | 278 | .SH SEE ALSO |
80a99f39 MK |
279 | .BR mq_close (3), |
280 | .BR mq_getattr (3), | |
281 | .BR mq_open (3), | |
282 | .BR mq_receive (3), | |
283 | .BR mq_send (3), | |
284 | .BR mq_unlink (3), | |
168e3472 MK |
285 | .BR mq_overview (7), |
286 | .BR sigevent (7) |