Debian Codegraph @

upstream/debian-unstable/man3/mq_notify.3

raw
1 '\" t
2 .\" Copyright 2006, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH mq_notify 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 mq_notify \- register for notification when a message is available
10 .SH LIBRARY
11 Real-time library
12 .RI ( librt ,\~ \-lrt )
13 .SH SYNOPSIS
14 .nf
15 .B #include <mqueue.h>
16 .BR "#include <signal.h> " "/* Definition of SIGEV_* constants */"
17 .P
18 .BI "int mq_notify(mqd_t " mqdes ", const struct sigevent *" sevp );
19 .fi
20 .SH DESCRIPTION
21 .BR mq_notify ()
22 allows the calling process to register or unregister for delivery of
23 an asynchronous notification when a new message arrives on
24 the empty message queue referred to by the message queue descriptor
25 .IR mqdes .
26 .P
27 The
28 .I sevp
29 argument is a pointer to a
30 .I sigevent
31 structure.
32 For the definition and general details of this structure, see
33 .BR sigevent (3type).
34 .P
35 If
36 .I sevp
37 is a non-null pointer, then
38 .BR mq_notify ()
39 registers the calling process to receive message notification.
40 The
41 .I sigev_notify
42 field of the
43 .I sigevent
44 structure to which
45 .I sevp
46 points specifies how notification is to be performed.
47 This field has one of the following values:
48 .TP
49 .B SIGEV_NONE
50 A "null" notification: the calling process is registered as the target
51 for notification, but when a message arrives, no notification is sent.
52 .\" When is SIGEV_NONE useful?
53 .TP
54 .B SIGEV_SIGNAL
55 Notify the process by sending the signal specified in
56 .IR sigev_signo .
57 See
58 .BR sigevent (3type)
59 for general details.
60 The
61 .I si_code
62 field of the
63 .I siginfo_t
64 structure will be set to
65 .BR SI_MESGQ .
66 In addition,
67 .\" I don't know of other implementations that set
68 .\" si_pid and si_uid -- MTK
69 .I si_pid
70 will be set to the PID of the process that sent the message, and
71 .I si_uid
72 will be set to the real user ID of the sending process.
73 .TP
74 .B SIGEV_THREAD
75 Upon message delivery, invoke
76 .I sigev_notify_function
77 as if it were the start function of a new thread.
78 See
79 .BR sigevent (3type)
80 for details.
81 .P
82 Only one process can be registered to receive notification
83 from a message queue.
84 .P
85 If
86 .I sevp
87 is NULL, and the calling process is currently registered to receive
88 notifications for this message queue, then the registration is removed;
89 another process can then register to receive a message notification
90 for this queue.
91 .P
92 Message notification occurs only when a new message arrives and
93 the queue was previously empty.
94 If the queue was not empty at the time
95 .BR mq_notify ()
96 was called, then a notification will occur only after
97 the queue is emptied and a new message arrives.
98 .P
99 If another process or thread is waiting to read a message
100 from an empty queue using
101 .BR mq_receive (3),
102 then any message notification registration is ignored:
103 the message is delivered to the process or thread calling
104 .BR mq_receive (3),
105 and the message notification registration remains in effect.
106 .P
107 Notification occurs once: after a notification is delivered,
108 the notification registration is removed,
109 and another process can register for message notification.
110 If the notified process wishes to receive the next notification,
111 it can use
112 .BR mq_notify ()
113 to request a further notification.
114 This should be done before emptying all unread messages from the queue.
115 (Placing the queue in nonblocking mode is useful for emptying
116 the queue of messages without blocking once it is empty.)
117 .SH RETURN VALUE
118 On success
119 .BR mq_notify ()
120 returns 0;
121 on error, \-1 is returned, with
122 .I errno
123 set to indicate the error.
124 .SH ERRORS
125 .TP
126 .B EBADF
127 The message queue descriptor specified in
128 .I mqdes
129 is invalid.
130 .TP
131 .B EBUSY
132 Another process has already registered to receive notification
133 for this message queue.
134 .TP
135 .B EINVAL
136 .I sevp\->sigev_notify
137 is not one of the permitted values;
138 or
139 .I sevp\->sigev_notify
140 is
141 .B SIGEV_SIGNAL
142 and
143 .I sevp\->sigev_signo
144 is not a valid signal number.
145 .TP
146 .B ENOMEM
147 Insufficient memory.
148 .P
149 POSIX.1-2008 says that an implementation
150 .I may
151 generate an
152 .B EINVAL
153 .\" Linux does not do this
154 error if
155 .I sevp
156 is NULL, and the caller is not currently registered to receive
157 notifications for the queue
158 .IR mqdes .
159 .SH ATTRIBUTES
160 For an explanation of the terms used in this section, see
161 .BR attributes (7).
162 .TS
163 allbox;
164 lbx lb lb
165 l l l.
166 Interface Attribute Value
167 T{
168 .na
169 .nh
170 .BR mq_notify ()
171 T} Thread safety MT-Safe
172 .TE
173 .SH VERSIONS
174 .SS C library/kernel differences
175 In the glibc implementation, the
176 .BR mq_notify ()
177 library function is implemented on top of the system call of the same name.
178 When
179 .I sevp
180 is NULL, or specifies a notification mechanism other than
181 .BR SIGEV_THREAD ,
182 the library function directly invokes the system call.
183 For
184 .BR SIGEV_THREAD ,
185 much of the implementation resides within the library,
186 rather than the kernel.
187 (This is necessarily so,
188 since the thread involved in handling the notification is one
189 that must be managed by the C library POSIX threads implementation.)
190 The implementation involves the use of a raw
191 .BR netlink (7)
192 socket and creates a new thread for each notification that is
193 delivered to the process.
194 .SH STANDARDS
195 POSIX.1-2008.
196 .SH HISTORY
197 POSIX.1-2001.
198 .SH EXAMPLES
199 The following program registers a notification request for the
200 message queue named in its command-line argument.
201 Notification is performed by creating a thread.
202 The thread executes a function which reads one message from the
203 queue and then terminates the process.
204 .SS Program source
205 .\" SRC BEGIN (mq_notify.c)
206 .EX
207 #include <err.h>
208 #include <mqueue.h>
209 #include <pthread.h>
210 #include <signal.h>
211 #include <stdio.h>
212 #include <stdlib.h>
213 #include <unistd.h>
214 \&
215 static void /* Thread start function */
216 tfunc(union sigval sv)
217 {
218 struct mq_attr attr;
219 ssize_t nr;
220 void *buf;
221 mqd_t mqdes = *((mqd_t *) sv.sival_ptr);
222 \&
223 /* Determine max.\& msg size; allocate buffer to receive msg */
224 \&
225 if (mq_getattr(mqdes, &attr) == \-1)
226 err(EXIT_FAILURE, "mq_getattr");
227 buf = malloc(attr.mq_msgsize);
228 if (buf == NULL)
229 err(EXIT_FAILURE, "malloc");
230 \&
231 nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL);
232 if (nr == \-1)
233 err(EXIT_FAILURE, "mq_receive");
234 \&
235 printf("Read %zd bytes from MQ\[rs]n", nr);
236 free(buf);
237 exit(EXIT_SUCCESS); /* Terminate the process */
238 }
239 \&
240 int
241 main(int argc, char *argv[])
242 {
243 mqd_t mqdes;
244 struct sigevent sev;
245 \&
246 if (argc != 2) {
247 fprintf(stderr, "Usage: %s <mq\-name>\[rs]n", argv[0]);
248 exit(EXIT_FAILURE);
249 }
250 \&
251 mqdes = mq_open(argv[1], O_RDONLY);
252 if (mqdes == (mqd_t) \-1)
253 err(EXIT_FAILURE, "mq_open");
254 \&
255 sev.sigev_notify = SIGEV_THREAD;
256 sev.sigev_notify_function = tfunc;
257 sev.sigev_notify_attributes = NULL;
258 sev.sigev_value.sival_ptr = &mqdes; /* Arg.\& to thread func. */
259 if (mq_notify(mqdes, &sev) == \-1)
260 err(EXIT_FAILURE, "mq_notify");
261 \&
262 pause(); /* Process will be terminated by thread function */
263 }
264 .EE
265 .\" SRC END
266 .SH SEE ALSO
267 .BR mq_close (3),
268 .BR mq_getattr (3),
269 .BR mq_open (3),
270 .BR mq_receive (3),
271 .BR mq_send (3),
272 .BR mq_unlink (3),
273 .BR mq_overview (7),
274 .BR sigevent (3type)