2 .\" Hey Emacs! This file is -*- nroff -*- source.
4 .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
6 .\" Permission is granted to make and distribute verbatim copies of this
7 .\" manual provided the copyright notice and this permission notice are
8 .\" preserved on all copies.
10 .\" Permission is granted to copy and distribute modified versions of this
11 .\" manual under the conditions for verbatim copying, provided that the
12 .\" entire resulting derived work is distributed under the terms of a
13 .\" permission notice identical to this one.
15 .\" Since the Linux kernel and libraries are constantly changing, this
16 .\" manual page may be incorrect or out-of-date. The author(s) assume no
17 .\" responsibility for errors or omissions, or for damages resulting from
18 .\" the use of the information contained herein. The author(s) may not
19 .\" have taken the same level of care in the production of this manual,
20 .\" which is licensed free of charge, as they might when working
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
26 .\" Japanese Version Copyright (c) 2006 Akihiro MOTOKI all rights reserved.
27 .\" Translated 2006-07-31, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
28 .\" Updated 2010-04-18, Akihiro MOTOKI, LDP v3.24
29 .\" Updated 2010-10-27, Akihiro Motoki, LDP v3.29
31 .TH MQ_NOTIFY 3 2010-10-04 "Linux" "Linux Programmer's Manual"
34 .\"O mq_notify \- register for notification when a message is available
35 mq_notify \- メッセージ到着時に通知を行うよう登録する
39 .B #include <mqueue.h>
41 .BI "int mq_notify(mqd_t " mqdes ", const struct sigevent *" notification );
44 .\"O Link with \fI\-lrt\fP.
49 .\"O allows the calling process to register or unregister for delivery of
50 .\"O an asynchronous notification when a new message arrives on
51 .\"O the empty message queue referred to by the descriptor
56 で参照される空のメッセージキューに新しくメッセージが到着した時に
57 非同期の通知 (notification) の配送が行われるように登録したり、
62 .\"O argument is a pointer to a
65 .\"O For the definition and general details of this structure, see
66 .\"O .BR sigevent (7).
77 .\"O is a non-NULL pointer, then
79 .\"O registers the calling process to receive message notification.
83 はメッセージ通知を受け取るように呼び出し元のプロセスを登録する。
88 .\"O structure to which
90 .\"O points specifies how notification is to be performed.
91 .\"O This field has one of the following values:
97 フィールドは、どのような通知を行うのかを指定する。
101 .\"O A "null" notification: the calling process is registered as the target
102 .\"O for notification, but when a message arrives, no notification is sent.
103 「空の (null)」の通知: 呼び出し元のプロセスを通知の宛先として登録するが、
104 実際にはメッセージが到着した時に通知は送られない。
105 .\" When is SIGEV_NONE useful?
108 .\"O Notify the process by sending the signal specified in
109 .\"O .IR sigev_signo .
111 .\"O .BR sigevent (7)
112 .\"O for general details.
114 で指定されたシグナルを送って、プロセスに通知する。
122 .\"O structure will be set to
131 .\" I don't know of other implementations that set
132 .\" si_pid and si_uid -- MTK
134 .\"O will be set to the PID of the process that sent the message, and
136 .\"O will be set to the real user ID of the sending process.
139 にはメッセージを送信したプロセスの PID が、
141 には送信プロセスの実ユーザ ID が設定される。
144 .\"O Upon message delivery, invoke
145 .\"O .I sigev_notify_function
146 .\"O as if it were the start function of a new thread.
148 .\"O .BR sigevent (7)
151 .I sigev_notify_function
152 があたかも新しいスレッドの開始関数であるかのように起動される。
157 .\"O Only one process can be registered to receive notification
158 .\"O from a message queue.
159 一つのメッセージキューから通知を受信するように登録できるプロセスは
164 .\"O is NULL, and the calling process is currently registered to receive
165 .\"O notifications for this message queue, then the registration is removed;
166 .\"O another process can then register to receive a message notification
169 が NULL で、かつ呼び出し元のプロセスがこのメッセージキューからの
170 通知を受信するに現在登録している場合、登録を削除する。
171 これ以降、別のプロセスがこのメッセージキューから通知を受信するように
174 .\"O Message notification only occurs when a new message arrives and
175 .\"O the queue was previously empty.
176 .\"O If the queue was not empty at the time
177 .\"O .BR mq_notify ()
178 .\"O was called, then a notification will only occur after
179 .\"O the queue is emptied and a new message arrives.
180 メッセージ通知は、それまで空のキューに新しいメッセージが到着した
183 が呼び出された時にそのキューが空でない場合、
184 そのキューが空になり、その後新しいメッセージが到着した時に
187 .\"O If another process or thread is waiting to read a message
188 .\"O from an empty queue using
189 .\"O .BR mq_receive (3),
190 .\"O then any message notification registration is ignored:
191 .\"O the message is delivered to the process or thread calling
192 .\"O .BR mq_receive (3),
193 .\"O and the message notification registration remains in effect.
196 を使って、空のキューからメッセージの読み出しを待っている場合、
200 を呼び出しているプロセスやスレッドに配送され、
201 メッセージ通知の登録は効力を持ったままとなる。
203 .\"O Notification occurs once: after a notification is delivered,
204 .\"O the notification registration is removed,
205 .\"O and another process can register for message notification.
206 .\"O If the notified process wishes to receive the next notification,
208 .\"O .BR mq_notify ()
209 .\"O to request a further notification.
210 .\"O This should be done before emptying all unread messages from the queue.
211 .\"O (Placing the queue in nonblocking mode is useful for emptying
212 .\"O the queue of messages without blocking once it is empty.)
213 通知は一度だけ行われる。通知が送られた後は、通知要求の登録は削除され、
214 別のプロセスがメッセージ通知を受信するように登録できるようになる。
215 通知を受けたプロセスが次の通知も受信したい場合は、
217 を使ってその後の通知も受けるように要求することができる。
219 を再度呼び出すのは、読み出していないメッセージを全部読み出して
221 (キューからのメッセージ読み出しをキューが空になった時に
222 停止 (block) せずに行うには、キューを非停止モード (non-blocking mode)
224 .\"O .SH RETURN VALUE
227 .\"O .BR mq_notify ()
228 .\"O returns 0; on error, \-1 is returned, with
230 .\"O set to indicate the error.
233 は 0 を返す。エラーの場合、\-1 を返し、
240 .\"O The descriptor specified in
247 .\"O Another process has already registered to receive notification
248 .\"O for this message queue.
250 このメッセージキューに対する通知を受信するように登録している。
253 .\"O .I sevp\->sigev_notify
254 .\"O is not one of the permitted values; or
255 .\"O .I sevp\->sigev_notify
259 .\"O .I sevp\->sigev_signo
260 .\"O is not a valid signal number.
261 .I sevp\->sigev_notify
263 .I sevp\->sigev_notify
267 .I sevp\->sigev_signo
271 .\"O Insufficient memory.
274 .\"O POSIX.1-2008 says that an implementation
278 .\"O .\" Linux does not do this
281 .\"O is NULL, and the caller is not currently registered to receive
282 .\"O notifications for the queue
286 が NULL で、呼び出し元のプロセスがキュー
288 に関する通知を受信するように登録されていない場合、エラー
290 を生成するような実装を行っても「よい」ことになっている。
291 .\" Linux の実装では EINVAL は生成されない
292 .\"O .SH CONFORMING TO
297 .\"O The following program registers a notification request for the
298 .\"O message queue named in its command-line argument.
299 .\"O Notification is performed by creating a thread.
300 .\"O The thread executes a function which reads one message from the
301 .\"O queue and then terminates the process.
303 コマンドライン引き数で指定された名前のメッセージキューへの
304 通知要求を登録し、通知はスレッドの作成によって行われる。
305 そのスレッドは、そのキューからメッセージを一つ読み出してから、
315 #define handle_error(msg) \\
316 do { perror(msg); exit(EXIT_FAILURE); } while (0)
318 .\"O static void /* Thread start function */
319 static void /* スレッド開始関数 */
320 tfunc(union sigval sv)
325 mqd_t mqdes = *((mqd_t *) sv.sival_ptr);
327 .\"O /* Determine max. msg size; allocate buffer to receive msg */
329 メッセージ受信用のバッファを確保する */
331 if (mq_getattr(mqdes, &attr) == \-1)
332 handle_error("mq_getattr");
333 buf = malloc(attr.mq_msgsize);
335 handle_error("malloc");
337 nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL);
339 handle_error("mq_receive");
341 printf("Read %ld bytes from MQ\\n", (long) nr);
343 .\"O exit(EXIT_SUCCESS); /* Terminate the process */
344 exit(EXIT_SUCCESS); /* プロセスを終了する */
348 main(int argc, char *argv[])
354 fprintf(stderr, "Usage: %s <mq-name>\\n", argv[0]);
358 mqdes = mq_open(argv[1], O_RDONLY);
359 if (mqdes == (mqd_t) \-1)
360 handle_error("mq_open");
362 sev.sigev_notify = SIGEV_THREAD;
363 sev.sigev_notify_function = tfunc;
364 sev.sigev_notify_attributes = NULL;
365 .\"O sev.sigev_value.sival_ptr = &mqdes; /* Arg. to thread func. */
366 sev.sigev_value.sival_ptr = &mqdes; /* スレッド関数に渡す引き数 */
367 if (mq_notify(mqdes, &sev) == \-1)
368 handle_error("mq_notify");
370 .\"O pause(); /* Process will be terminated by thread function */
371 pause(); /* プロセスはスレッド関数により終了される */