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
12 mq_notify — notify process that a message is available (REALTIME)
13
15 #include <mqueue.h>
16 int mq_notify(mqd_t mqdes, const struct sigevent *notification);
18
20 If the argument notification is not NULL, this function shall register
21 the calling process to be notified of message arrival at an empty mes‐
22 sage queue associated with the specified message queue descriptor,
23 mqdes. The notification specified by the notification argument shall
24 be sent to the process when the message queue transitions from empty to
25 non-empty. At any time, only one process may be registered for notifi‐
26 cation by a message queue. If the calling process or any other process
27 has already registered for notification of message arrival at the spec‐
28 ified message queue, subsequent attempts to register for that message
29 queue shall fail.
30 If notification is NULL and the process is currently registered for
32 notification by the specified message queue, the existing registration
33 shall be removed.
34 When the notification is sent to the registered process, its registra‐
36 tion shall be removed. The message queue shall then be available for
37 registration.
38 If a process has registered for notification of message arrival at a
40 message queue and some thread is blocked in mq_receive() or mq_time‐
41 dreceive() waiting to receive a message when a message arrives at the
42 queue, the arriving message shall satisfy the appropriate mq_receive()
43 or mq_timedreceive(), respectively. The resulting behavior is as if the
44 message queue remains empty, and no notification shall be sent.
45
47 Upon successful completion, the mq_notify() function shall return a
48 value of zero; otherwise, the function shall return a value of -1 and
49 set errno to indicate the error.
50
52 The mq_notify() function shall fail if:
53 EBADF The mqdes argument is not a valid message queue descriptor.
55 EBUSY A process is already registered for notification by the message
57 queue.
58 The mq_notify() function may fail if:
60 EINVAL The notification argument is NULL and the process is currently
62 not registered.
63 The following sections are informative.
65
67 The following program registers a notification request for the message
68 queue named in its command-line argument. Notification is performed by
69 creating a thread. The thread executes a function which reads one mes‐
70 sage from the queue and then terminates the process.
71 #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‐2017, <mqueue.h>
152
154 Portions of this text are reprinted and reproduced in electronic form
155 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
156 table Operating System Interface (POSIX), The Open Group Base Specifi‐
157 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
158 Electrical and Electronics Engineers, Inc and The Open Group. In the
159 event of any discrepancy between this version and the original IEEE and
160 The Open Group Standard, the original IEEE and The Open Group Standard
161 is the referee document. The original Standard can be obtained online
162 at http://www.opengroup.org/unix/online.html .
163 Any typographical or formatting errors that appear in this page are
165 most likely to have been introduced during the conversion of the source
166 files to man page format. To report such errors, see https://www.ker‐
167 nel.org/doc/man-pages/reporting_bugs.html .
168IEEE/The Open Group 2017 MQ_NOTIFY(3P)