1 .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .TH MQ_NOTIFY 3 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
7 mq_notify \- register for notification when a message is available
10 .RI ( librt ", " \-lrt )
13 .B #include <mqueue.h>
14 .BR "#include <signal.h> " "/* Definition of SIGEV_* constants */"
16 .BI "int mq_notify(mqd_t " mqdes ", const struct sigevent *" sevp );
20 allows the calling process to register or unregister for delivery of
21 an asynchronous notification when a new message arrives on
22 the empty message queue referred to by the message queue descriptor
27 argument is a pointer to a
30 For the definition and general details of this structure, see
35 is a non-null pointer, then
37 registers the calling process to receive message notification.
44 points specifies how notification is to be performed.
45 This field has one of the following values:
48 A "null" notification: the calling process is registered as the target
49 for notification, but when a message arrives, no notification is sent.
50 .\" When is SIGEV_NONE useful?
53 Notify the process by sending the signal specified in
62 structure will be set to
65 .\" I don't know of other implementations that set
66 .\" si_pid and si_uid -- MTK
68 will be set to the PID of the process that sent the message, and
70 will be set to the real user ID of the sending process.
73 Upon message delivery, invoke
74 .I sigev_notify_function
75 as if it were the start function of a new thread.
80 Only one process can be registered to receive notification
85 is NULL, and the calling process is currently registered to receive
86 notifications for this message queue, then the registration is removed;
87 another process can then register to receive a message notification
90 Message notification occurs only when a new message arrives and
91 the queue was previously empty.
92 If the queue was not empty at the time
94 was called, then a notification will occur only after
95 the queue is emptied and a new message arrives.
97 If another process or thread is waiting to read a message
98 from an empty queue using
100 then any message notification registration is ignored:
101 the message is delivered to the process or thread calling
103 and the message notification registration remains in effect.
105 Notification occurs once: after a notification is delivered,
106 the notification registration is removed,
107 and another process can register for message notification.
108 If the notified process wishes to receive the next notification,
111 to request a further notification.
112 This should be done before emptying all unread messages from the queue.
113 (Placing the queue in nonblocking mode is useful for emptying
114 the queue of messages without blocking once it is empty.)
118 returns 0; on error, \-1 is returned, with
120 set to indicate the error.
124 The message queue descriptor specified in
129 Another process has already registered to receive notification
130 for this message queue.
133 .I sevp\->sigev_notify
134 is not one of the permitted values; or
135 .I sevp\->sigev_notify
139 .I sevp\->sigev_signo
140 is not a valid signal number.
145 POSIX.1-2008 says that an implementation
149 .\" Linux does not do this
152 is NULL, and the caller is not currently registered to receive
153 notifications for the queue
156 For an explanation of the terms used in this section, see
164 Interface Attribute Value
167 T} Thread safety MT-Safe
176 .SS C library/kernel differences
177 In the glibc implementation, the
179 library function is implemented on top of the system call of the same name.
182 is NULL, or specifies a notification mechanism other than
184 the library function directly invokes the system call.
187 much of the implementation resides within the library,
188 rather than the kernel.
189 (This is necessarily so,
190 since the thread involved in handling the notification is one
191 that must be managed by the C library POSIX threads implementation.)
192 The implementation involves the use of a raw
194 socket and creates a new thread for each notification that is
195 delivered to the process.
197 The following program registers a notification request for the
198 message queue named in its command-line argument.
199 Notification is performed by creating a thread.
200 The thread executes a function which reads one message from the
201 queue and then terminates the process.
211 #define handle_error(msg) \e
212 do { perror(msg); exit(EXIT_FAILURE); } while (0)
214 static void /* Thread start function */
215 tfunc(union sigval sv)
220 mqd_t mqdes = *((mqd_t *) sv.sival_ptr);
222 /* Determine max. msg size; allocate buffer to receive msg */
224 if (mq_getattr(mqdes, &attr) == \-1)
225 handle_error("mq_getattr");
226 buf = malloc(attr.mq_msgsize);
228 handle_error("malloc");
230 nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL);
232 handle_error("mq_receive");
234 printf("Read %zd bytes from MQ\en", nr);
236 exit(EXIT_SUCCESS); /* Terminate the process */
240 main(int argc, char *argv[])
246 fprintf(stderr, "Usage: %s <mq\-name>\en", argv[0]);
250 mqdes = mq_open(argv[1], O_RDONLY);
251 if (mqdes == (mqd_t) \-1)
252 handle_error("mq_open");
254 sev.sigev_notify = SIGEV_THREAD;
255 sev.sigev_notify_function = tfunc;
256 sev.sigev_notify_attributes = NULL;
257 sev.sigev_value.sival_ptr = &mqdes; /* Arg. to thread func. */
258 if (mq_notify(mqdes, &sev) == \-1)
259 handle_error("mq_notify");
261 pause(); /* Process will be terminated by thread function */