1MQ_NOTIFY(3P) POSIX Programmer's Manual MQ_NOTIFY(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 mq_notify — notify process that a message is available (REALTIME)
14
16 #include <mqueue.h>
17 int mq_notify(mqd_t mqdes, const struct sigevent *notification);
19
21 If the argument notification is not NULL, this function shall register
22 the calling process to be notified of message arrival at an empty mes‐
23 sage queue associated with the specified message queue descriptor,
24 mqdes. The notification specified by the notification argument shall
25 be sent to the process when the message queue transitions from empty to
26 non-empty. At any time, only one process may be registered for notifi‐
27 cation by a message queue. If the calling process or any other process
28 has already registered for notification of message arrival at the spec‐
29 ified message queue, subsequent attempts to register for that message
30 queue shall fail.
31 If notification is NULL and the process is currently registered for
33 notification by the specified message queue, the existing registration
34 shall be removed.
35 When the notification is sent to the registered process, its registra‐
37 tion shall be removed. The message queue shall then be available for
38 registration.
39 If a process has registered for notification of message arrival at a
41 message queue and some thread is blocked in mq_receive() or mq_time‐
42 dreceive() waiting to receive a message when a message arrives at the
43 queue, the arriving message shall satisfy the appropriate mq_receive()
44 or mq_timedreceive(), respectively. The resulting behavior is as if the
45 message queue remains empty, and no notification shall be sent.
46
48 Upon successful completion, the mq_notify() function shall return a
49 value of zero; otherwise, the function shall return a value of −1 and
50 set errno to indicate the error.
51
53 The mq_notify() function shall fail if:
54 EBADF The mqdes argument is not a valid message queue descriptor.
56 EBUSY A process is already registered for notification by the message
58 queue.
59 The mq_notify() function may fail if:
61 EINVAL The notification argument is NULL and the process is currently
63 not registered.
64 The following sections are informative.
66
68 The following program registers a notification request for the message
69 queue named in its command-line argument. Notification is performed by
70 creating a thread. The thread executes a function which reads one mes‐
71 sage from the queue and then terminates the process.
72 #include <pthread.h>
74 #include <mqueue.h>
75 #include <assert.h>
76 #include <stdio.h>
77 #include <stdlib.h>
78 #include <unistd.h>
79 static void /* Thread start function */
81 tfunc(union sigval sv)
82 {
83 struct mq_attr attr;
84 ssize_t nr;
85 void *buf;
86 mqd_t mqdes = *((mqd_t *) sv.sival_ptr);
87 /* Determine maximum msg size; allocate buffer to receive msg */
89 if (mq_getattr(mqdes, &attr) == -1) {
91 perror("mq_getattr");
92 exit(EXIT_FAILURE);
93 }
94 buf = malloc(attr.mq_msgsize);
95 if (buf == NULL) {
97 perror("malloc");
98 exit(EXIT_FAILURE);
99 }
100 nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL);
102 if (nr == -1) {
103 perror("mq_receive");
104 exit(EXIT_FAILURE);
105 }
106 printf("Read %ld bytes from message queue\n", (long) nr);
108 free(buf);
109 exit(EXIT_SUCCESS); /* Terminate the process */
110 }
111 int
113 main(int argc, char *argv[])
114 {
115 mqd_t mqdes;
116 struct sigevent not;
117 assert(argc == 2);
119 mqdes = mq_open(argv[1], O_RDONLY);
121 if (mqdes == (mqd_t) -1) {
122 perror("mq_open");
123 exit(EXIT_FAILURE);
124 }
125 not.sigev_notify = SIGEV_THREAD;
127 not.sigev_notify_function = tfunc;
128 not.sigev_notify_attributes = NULL;
129 not.sigev_value.sival_ptr = &mqdes; /* Arg. to thread func. */
130 if (mq_notify(mqdes, ¬) == -1) {
131 perror("mq_notify");
132 exit(EXIT_FAILURE);
133 }
134 pause(); /* Process will be terminated by thread function */
136 }
137
139 None.
140
142 None.
143
145 None.
146
148 mq_open(), mq_send(), mq_receive(), msgctl(), msgget(), msgrcv(),
149 msgsnd()
150 The Base Definitions volume of POSIX.1‐2008, <mqueue.h>
152
154 Portions of this text are reprinted and reproduced in electronic form
155 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
156 -- Portable Operating System Interface (POSIX), The Open Group Base
157 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
158 cal and Electronics Engineers, Inc and The Open Group. (This is
159 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
160 event of any discrepancy between this version and the original IEEE and
161 The Open Group Standard, the original IEEE and The Open Group Standard
162 is the referee document. The original Standard can be obtained online
163 at http://www.unix.org/online.html .
164 Any typographical or formatting errors that appear in this page are
166 most likely to have been introduced during the conversion of the source
167 files to man page format. To report such errors, see https://www.ker‐
168 nel.org/doc/man-pages/reporting_bugs.html .
169IEEE/The Open Group 2013 MQ_NOTIFY(3P)