]>
Commit | Line | Data |
---|---|---|
80a99f39 MK |
1 | '\" t |
2 | .\" Hey Emacs! This file is -*- nroff -*- source. | |
3 | .\" | |
c11b1abf | 4 | .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
80a99f39 MK |
5 | .\" |
6 | .\" Permission is granted to make and distribute verbatim copies of this | |
7 | .\" manual provided the copyright notice and this permission notice are | |
8 | .\" preserved on all copies. | |
9 | .\" | |
10 | .\" Permission is granted to copy and distribute modified versions of this | |
11 | .\" manual under the conditions for verbatim copying, provided that the | |
12 | .\" entire resulting derived work is distributed under the terms of a | |
13 | .\" permission notice identical to this one. | |
c13182ef | 14 | .\" |
80a99f39 MK |
15 | .\" Since the Linux kernel and libraries are constantly changing, this |
16 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
17 | .\" responsibility for errors or omissions, or for damages resulting from | |
10d76543 MK |
18 | .\" the use of the information contained herein. The author(s) may not |
19 | .\" have taken the same level of care in the production of this manual, | |
20 | .\" which is licensed free of charge, as they might when working | |
21 | .\" professionally. | |
c13182ef | 22 | .\" |
80a99f39 MK |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
25 | .\" | |
168e3472 | 26 | .TH MQ_NOTIFY 3 2010-09-19 "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> | |
32 | .sp | |
c9e83f06 | 33 | .BI "int mq_notify(mqd_t " mqdes ", const struct sigevent *" notification ); |
80a99f39 | 34 | .fi |
1b2d3fca MK |
35 | .sp |
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 | |
80a99f39 MK |
41 | the empty message queue referred to by the descriptor |
42 | .IR mqdes . | |
43 | ||
c13182ef | 44 | The |
80a99f39 | 45 | .I notification |
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 |
80a99f39 | 53 | .I notification |
c13182ef | 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 |
80a99f39 MK |
62 | .I notification |
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. | |
101 | ||
c13182ef | 102 | If |
80a99f39 MK |
103 | .I notification |
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 MK |
107 | for this queue. |
108 | ||
c13182ef | 109 | Message notification only occurs 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 () | |
c13182ef | 113 | was called, then a notification will only occur after |
80a99f39 MK |
114 | the queue is emptied and a new message arrives. |
115 | ||
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 MK |
122 | and the message notification registration remains in effect. |
123 | ||
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 | |
c13182ef | 143 | The 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 | |
94e9d9fe | 152 | .I notification\->sigev_notify |
80a99f39 | 153 | is not one of the permitted values; or |
94e9d9fe | 154 | .I notification\->sigev_notify |
c13182ef MK |
155 | is |
156 | .B SIGEV_SIGNAL | |
157 | and | |
94e9d9fe | 158 | .I notification\->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 | |
170 | .I notification | |
171 | is NULL, and the caller is not currently registered to receive | |
172 | notifications for the queue | |
173 | .IR mqdes . | |
80a99f39 MK |
174 | .SH CONFORMING TO |
175 | POSIX.1-2001. | |
176 | .SH EXAMPLE | |
177 | The following program registers a notification request for the | |
178 | message queue named in its command-line argument. | |
179 | Notification is performed by creating a thread. | |
c13182ef | 180 | The thread executes a function which reads one message from the |
80a99f39 MK |
181 | queue and then terminates the process. |
182 | .nf | |
183 | ||
184 | #include <pthread.h> | |
185 | #include <mqueue.h> | |
80a99f39 MK |
186 | #include <stdio.h> |
187 | #include <stdlib.h> | |
188 | #include <unistd.h> | |
189 | ||
6a578b88 MK |
190 | #define handle_error(msg) \\ |
191 | do { perror(msg); exit(EXIT_FAILURE); } while (0) | |
80a99f39 MK |
192 | |
193 | static void /* Thread start function */ | |
194 | tfunc(union sigval sv) | |
195 | { | |
196 | struct mq_attr attr; | |
197 | ssize_t nr; | |
198 | void *buf; | |
199 | mqd_t mqdes = *((mqd_t *) sv.sival_ptr); | |
200 | ||
201 | /* Determine max. msg size; allocate buffer to receive msg */ | |
202 | ||
29059a65 | 203 | if (mq_getattr(mqdes, &attr) == \-1) |
6a578b88 | 204 | handle_error("mq_getattr"); |
80a99f39 | 205 | buf = malloc(attr.mq_msgsize); |
29059a65 | 206 | if (buf == NULL) |
6a578b88 | 207 | handle_error("malloc"); |
80a99f39 MK |
208 | |
209 | nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL); | |
29059a65 | 210 | if (nr == \-1) |
6a578b88 | 211 | handle_error("mq_receive"); |
80a99f39 | 212 | |
39ad75ab | 213 | printf("Read %ld bytes from MQ\\n", (long) nr); |
80a99f39 MK |
214 | free(buf); |
215 | exit(EXIT_SUCCESS); /* Terminate the process */ | |
216 | } | |
217 | ||
218 | int | |
219 | main(int argc, char *argv[]) | |
220 | { | |
221 | mqd_t mqdes; | |
222 | struct sigevent not; | |
223 | ||
6b34fb3f MK |
224 | if (argc != 2) { |
225 | fprintf(stderr, "Usage: %s <mq-name>\\n", argv[0]); | |
226 | exit(EXIT_FAILURE); | |
227 | } | |
80a99f39 MK |
228 | |
229 | mqdes = mq_open(argv[1], O_RDONLY); | |
29059a65 | 230 | if (mqdes == (mqd_t) \-1) |
6a578b88 | 231 | handle_error("mq_open"); |
80a99f39 MK |
232 | |
233 | not.sigev_notify = SIGEV_THREAD; | |
234 | not.sigev_notify_function = tfunc; | |
235 | not.sigev_notify_attributes = NULL; | |
236 | not.sigev_value.sival_ptr = &mqdes; /* Arg. to thread func. */ | |
29059a65 | 237 | if (mq_notify(mqdes, ¬) == \-1) |
6a578b88 | 238 | handle_error("mq_notify"); |
80a99f39 MK |
239 | |
240 | pause(); /* Process will be terminated by thread function */ | |
241 | } | |
242 | .fi | |
243 | .SH "SEE ALSO" | |
244 | .BR mq_close (3), | |
245 | .BR mq_getattr (3), | |
246 | .BR mq_open (3), | |
247 | .BR mq_receive (3), | |
248 | .BR mq_send (3), | |
249 | .BR mq_unlink (3), | |
168e3472 MK |
250 | .BR mq_overview (7), |
251 | .BR sigevent (7) |