1MQ_NOTIFY(3) Linux Programmer's Manual MQ_NOTIFY(3)
2
6 mq_notify - register for notification when a message is available
7
9 #include <mqueue.h>
10 int mq_notify(mqd_t mqdes, const struct sigevent *sevp);
12 Link with -lrt.
14
16 mq_notify() allows the calling process to register or unregister for
17 delivery of an asynchronous notification when a new message arrives on
18 the empty message queue referred to by the descriptor mqdes.
19 The sevp argument is a pointer to a sigevent structure. For the defi‐
21 nition and general details of this structure, see sigevent(7).
22 If sevp is a non-NULL pointer, then mq_notify() registers the calling
24 process to receive message notification. The sigev_notify field of the
25 sigevent structure to which sevp points specifies how notification is
26 to be performed. This field has one of the following values:
27 SIGEV_NONE
29 A "null" notification: the calling process is registered as the
30 target for notification, but when a message arrives, no notifi‐
31 cation is sent.
32 SIGEV_SIGNAL
34 Notify the process by sending the signal specified in
35 sigev_signo. See sigevent(7) for general details. The si_code
36 field of the siginfo_t structure will be set to SI_MESGQ. In
37 addition, si_pid will be set to the PID of the process that sent
38 the message, and si_uid will be set to the real user ID of the
39 sending process.
40 SIGEV_THREAD
42 Upon message delivery, invoke sigev_notify_function as if it
43 were the start function of a new thread. See sigevent(7) for
44 details.
45 Only one process can be registered to receive notification from a mes‐
47 sage queue.
48 If sevp is NULL, and the calling process is currently registered to
50 receive notifications for this message queue, then the registration is
51 removed; another process can then register to receive a message notifi‐
52 cation for this queue.
53 Message notification occurs only when a new message arrives and the
55 queue was previously empty. If the queue was not empty at the time
56 mq_notify() was called, then a notification will occur only after the
57 queue is emptied and a new message arrives.
58 If another process or thread is waiting to read a message from an empty
60 queue using mq_receive(3), then any message notification registration
61 is ignored: the message is delivered to the process or thread calling
62 mq_receive(3), and the message notification registration remains in
63 effect.
64 Notification occurs once: after a notification is delivered, the noti‐
66 fication registration is removed, and another process can register for
67 message notification. If the notified process wishes to receive the
68 next notification, it can use mq_notify() to request a further notifi‐
69 cation. This should be done before emptying all unread messages from
70 the queue. (Placing the queue in nonblocking mode is useful for empty‐
71 ing the queue of messages without blocking once it is empty.)
72
74 On success mq_notify() returns 0; on error, -1 is returned, with errno
75 set to indicate the error.
76
78 EBADF The descriptor specified in mqdes is invalid.
79 EBUSY Another process has already registered to receive notification
81 for this message queue.
82 EINVAL sevp->sigev_notify is not one of the permitted values; or
84 sevp->sigev_notify is SIGEV_SIGNAL and sevp->sigev_signo is not
85 a valid signal number.
86 ENOMEM Insufficient memory.
88 POSIX.1-2008 says that an implementation may generate an EINVAL error
90 if sevp is NULL, and the caller is not currently registered to receive
91 notifications for the queue mqdes.
92
94 POSIX.1-2001.
95
97 The following program registers a notification request for the message
98 queue named in its command-line argument. Notification is performed by
99 creating a thread. The thread executes a function which reads one mes‐
100 sage from the queue and then terminates the process.
101 #include <pthread.h>
103 #include <mqueue.h>
104 #include <stdio.h>
105 #include <stdlib.h>
106 #include <unistd.h>
107 #define handle_error(msg) \
109 do { perror(msg); exit(EXIT_FAILURE); } while (0)
110 static void /* Thread start function */
112 tfunc(union sigval sv)
113 {
114 struct mq_attr attr;
115 ssize_t nr;
116 void *buf;
117 mqd_t mqdes = *((mqd_t *) sv.sival_ptr);
118 /* Determine max. msg size; allocate buffer to receive msg */
120 if (mq_getattr(mqdes, &attr) == -1)
122 handle_error("mq_getattr");
123 buf = malloc(attr.mq_msgsize);
124 if (buf == NULL)
125 handle_error("malloc");
126 nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL);
128 if (nr == -1)
129 handle_error("mq_receive");
130 printf("Read %ld bytes from MQ\n", (long) nr);
132 free(buf);
133 exit(EXIT_SUCCESS); /* Terminate the process */
134 }
135 int
137 main(int argc, char *argv[])
138 {
139 mqd_t mqdes;
140 struct sigevent sev;
141 if (argc != 2) {
143 fprintf(stderr, "Usage: %s <mq-name>\n", argv[0]);
144 exit(EXIT_FAILURE);
145 }
146 mqdes = mq_open(argv[1], O_RDONLY);
148 if (mqdes == (mqd_t) -1)
149 handle_error("mq_open");
150 sev.sigev_notify = SIGEV_THREAD;
152 sev.sigev_notify_function = tfunc;
153 sev.sigev_notify_attributes = NULL;
154 sev.sigev_value.sival_ptr = &mqdes; /* Arg. to thread func. */
155 if (mq_notify(mqdes, &sev) == -1)
156 handle_error("mq_notify");
157 pause(); /* Process will be terminated by thread function */
159 }
160
162 mq_close(3), mq_getattr(3), mq_open(3), mq_receive(3), mq_send(3),
163 mq_unlink(3), mq_overview(7), sigevent(7)
164
166 This page is part of release 3.53 of the Linux man-pages project. A
167 description of the project, and information about reporting bugs, can
168 be found at http://www.kernel.org/doc/man-pages/.
169Linux 2010-10-04 MQ_NOTIFY(3)