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 mqd_t mq_notify(mqd_t mqdes, const struct sigevent *notification);
12
14 mq_notify() allows the calling process to register or unregister for
15 delivery of an asynchronous notification when a new message arrives on
16 the empty message queue referred to by the descriptor mqdes.
17 The notification argument is a pointer to a sigevent structure that is
19 defined something like the following:
20 union sigval { /* Data passed with notification */
22 int sival_int; /* Integer value */
23 void *sival_ptr; /* Pointer value */
24 };
25 struct sigevent {
27 int sigev_notify; /* Notification method */
28 int sigev_signo; /* Notification signal */
29 union sigval sigev_value; /* Data passed with notification */
30 void (*sigev_notify_function) (union sigval);
31 /* Function for thread notification */
32 void *sigev_notify_attributes;
33 /* Thread function attributes */
34 };
35 If notification is a non-NULL pointer, then mq_notify() registers the
37 calling process to receive message notification. The sigev_notify
38 field of the sigevent to which notification points specifies how noti‐
39 fication is to be performed. This field has one of the following val‐
40 ues:
41 SIGEV_NONE
43 A "null" notification: the calling process is registered as the
44 target for notification, but when a message arrives, no notifi‐
45 cation is sent.
46 SIGEV_SIGNAL
48 Notify the process by sending the signal specified in
49 sigev_signo. If the signal is caught with a signal handler that
50 was registered using the sigaction(2) SA_SIGINFO flag, then the
51 following fields are set in the siginfo_t structure that is
52 passed as the second argument of the handler: si_code is set to
53 SI_MESGQ; si_signo is set to the signal number; si_value is set
54 to the value specified in notification->sigev_value; si_pid is
55 set to the PID of the process that sent the message; and si_uid
56 is set to the real user ID of the sending process. The same
57 information is available if the signal is accepted using sig‐
58 waitinfo(2).
59 SIGEV_THREAD
61 Deliver notification by invoking notifica‐
62 tion->sigev_thread_function as the start function of a new
63 thread. The function is invoked with notification->sigev_value
64 as its sole argument. If notification->sigev_notify_attributes
65 is not NULL, then it should point to a pthread_attr_t structure
66 that defines attributes for the thread.
67 Only one process can be registered to receive notification from a mes‐
69 sage queue.
70 If notification is NULL, and the calling process is currently regis‐
72 tered to receive notifications for this message queue, then the regis‐
73 tration is removed; another process can then register to receive a mes‐
74 sage notification for this queue.
75 Message notification only occurs when a new message arrives and the
77 queue was previously empty. If the queue was not empty at the time
78 mq_notify() was called, then a notification will only occur after the
79 queue is emptied and a new message arrives.
80 If another process or thread is waiting to read a message from an empty
82 queue using mq_receive(), then any message notification registration is
83 ignored: the message is delivered to the process or thread calling
84 mq_receive(), and the message notification registration remains in
85 effect.
86 Notification occurs once: after a notification is delivered, the noti‐
88 fication registration is removed, and another process can register for
89 message notification. If the notified process wishes to receive the
90 next notification, it can use mq_notify() to request a further notifi‐
91 cation. This should be done before emptying all unread messages from
92 the queue. (Placing the queue in non-blocking mode is useful for emp‐
93 tying the queue of messages without blocking once it is empty.)
94
96 On success mq_notify() returns 0; on error, -1 is returned, with errno
97 set to indicate the error.
98
100 EBADF The descriptor specified in mqdes is invalid.
101 EBUSY Another process has already registered to receive notification
103 for this message queue.
104 EINVAL notification->sigev_notify is not one of the permitted values;
106 or notification->sigev_notify is SIGEV_SIGNAL and notifica‐
107 tion->sigev_signo is not a valid signal number.
108 ENOMEM Insufficient memory.
110
112 POSIX.1-2001.
113
115 The following program registers a notification request for the message
116 queue named in its command-line argument. Notification is performed by
117 creating a thread. The thread executes a function which reads one mes‐
118 sage from the queue and then terminates the process.
119 #include <pthread.h>
121 #include <mqueue.h>
122 #include <assert.h>
123 #include <stdio.h>
124 #include <stdlib.h>
125 #include <unistd.h>
126 #define die(msg) { perror(msg); exit(EXIT_FAILURE); }
128 static void /* Thread start function */
130 tfunc(union sigval sv)
131 {
132 struct mq_attr attr;
133 ssize_t nr;
134 void *buf;
135 mqd_t mqdes = *((mqd_t *) sv.sival_ptr);
136 /* Determine max. msg size; allocate buffer to receive msg */
138 if (mq_getattr(mqdes, &attr) == -1) die("mq_getattr");
140 buf = malloc(attr.mq_msgsize);
141 if (buf == NULL) die("malloc");
142 nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL);
144 if (nr == -1) die("mq_receive");
145 printf("Read %ld bytes from MQ\n", (long) nr);
147 free(buf);
148 exit(EXIT_SUCCESS); /* Terminate the process */
149 }
150 int
152 main(int argc, char *argv[])
153 {
154 mqd_t mqdes;
155 struct sigevent not;
156 assert(argc == 2);
158 mqdes = mq_open(argv[1], O_RDONLY);
160 if (mqdes == (mqd_t) -1) die("mq_open");
161 not.sigev_notify = SIGEV_THREAD;
163 not.sigev_notify_function = tfunc;
164 not.sigev_notify_attributes = NULL;
165 not.sigev_value.sival_ptr = &mqdes; /* Arg. to thread func. */
166 if (mq_notify(mqdes, ¬) == -1) die("mq_notify");
167 pause(); /* Process will be terminated by thread function */
169 }
170
172 mq_close(3), mq_getattr(3), mq_open(3), mq_receive(3), mq_send(3),
173 mq_unlink(3), mq_overview(7)
174Linux 2.6.16 2006-02-25 MQ_NOTIFY(3)