リナックスコマンド

mq_notifyのヘルプ・マニュアル

日本語 英語

• help
• man

mq_notify --help

man mq_notify

MQ_NOTIFY(3) Linux Programmer’s Manual MQ_NOTIFY(3) 名前 mq_notify - メッセージ到着時に通知を行うよう登録する 書式 #include mqd_t mq_notify(mqd_t mqdes, const struct sigevent *notification); -lrt でリンクする。 説明 mq_notify() を使うと、ディスクリプタ mqdes で参照される空のメッセージキ ューに新しくメッセージが到着した時に非同期の通知 (notification) の配 送 の登録/解除を行うことができる。 notification 引き数は sigevent 構造体へのポインタである。 sigevent 構造 体は以下のような感じで定義されている: union sigval { /* Data passed with notification */ int sival_int; /* Integer value */ void *sival_ptr; /* Pointer value */ }; struct sigevent { int sigev_notify; /* Notification method */ int sigev_signo; /* Notification signal */ union sigval sigev_value; /* Data passed with notification */ void (*sigev_notify_function) (union sigval); /* Function for thread notification */ void *sigev_notify_attributes; /* Thread function attributes */ }; notification が NULL でないポインタであれば、 mq_notify() はメッセー ジ 通 知を受け取るように呼び出し元のプロセスを登録する。 notification が指 す sigevent の sigev_notify フィールドは、どのような通知を行うのかを 指 定する。このフィールドは以下の値のいずれかを持つ。 SIGEV_NONE 「 空の (null)」の通知: 呼び出し元のプロセスを通知の宛先として登 録するが、実際にはメッセージが到着した時に通知は送られない。 SIGEV_SIGNAL sigev_signo で指定されたシグナルを送って、プロセスに通知す る 。 sigaction(2) の SA_SIGINFO フラグで登録されたシグナルハンドラで そのシグナルが捕捉された場合、シグナルハンドラの第二引き数として 渡 される siginfo_t 構造体の各フィールドは以下のように設定される 。 si_code には SI_MESGQ が設定される。 si_signo にはシグナル 番 号 が設定される。 si_value には notification->sigev_value で指定 した値が設定される。 si_pid にはメッセージを送信したプロセ ス の PID が 、 si_uid には送信プロセスの実ユーザ ID が設定される。 sigwaitinfo(2) を使ってシグナルを受信する場合も、同じ情報が得 ら れる。 SIGEV_THREAD 新 しいスレッドの開始関数として notification->sigev_thread_func- tion を起動することで通知を行う。起動時の関数の引き数と し て は notification->sigev_value だ け が 渡 さ れ る 。 notifica- tion->sigev_notify_attributes は、NULL 以外の場合、そのスレッ ド の属性を定義する pthread_attr_t 構造体へのポインタとなっている必 要がある (pthread_attr_init(3) 参照)。 一つのメッセージキューから通知を受信するように登録できるプロセスは一 つ だけである。 notification が NULL で、かつ呼び出し元のプロセスがこのメッセージキュー からの通知を受信するに現在登録している場合、登録を削除する。これ以降 、 別 のプロセスがこのメッセージキューから通知を受信するように登録できるよ うになる。 メッセージ通知は、それまで空のキューに新しいメッセージが到着した場合 に のみ行われる。 mq_notify() が呼び出された時にそのキューが空でない場合、 そのキューが空になり、その後新しいメッセージが到着した時に初めて通知 が 行われることになる。 別のプロセスやスレッドが mq_receive(3) を使って、空のキューからメッセー ジの読み出しを待っている場合、メッセージ通知の登録は全て無視される。 メ ッセージは mq_receive(3) を呼び出しているプロセスやスレッドに配送され、 メッセージ通知の登録は効力を持ったままとなる。 通知は一度だけ行われる。通知が送られた後は、通知要求の登録は削除され 、 別 のプロセスがメッセージ通知を受信するように登録できるようになる。通知 を受けたプロセスが次の通知も受信したい場合は、 mq_notify() を使ってその 後の通知も受けるように要求することができる。 mq_notify() を再度呼び出す のは、読み出していないメッセージを全部読み出してキューが空になる前に す べ きである (キューからのメッセージ読み出しをキューが空になった時に停止 (block) せずに行うには、キューを非停止モード (non-blocking mode) に設定 しておくとよい)。 返り値 成 功 すると、 mq_notify() は 0 を返す。エラーの場合、-1 を返し、 errno をエラーを示す値に設定する。 エラー EBADF mqdes に指定されたディスクリプタが不正である。 EBUSY 別のプロセスがすでにこのメッセージキューに対する通知を受信するよ うに登録している。 EINVAL notification->sigev_notify が許可された値のいずれでもない。もし くは notification->sigev_notify が SIGEV_SIGNAL だ が notifica- tion->sigev_signo が有効なシグナル番号ではない。 ENOMEM 必要なメモリがなかった。 準拠 POSIX.1-2001. 例 以 下のプログラムは、コマンドライン引き数で指定された名前のメッセージキ ューへの通知要求を登録し、通知はスレッドの作成で行われる。そのスレッ ド は 、そのキューからメッセージを一つ読み出してから、プロセスを終了する関 数を実行する。 #include #include #include #include #include #include #define handle_error(msg) \ do { perror(msg); exit(EXIT_FAILURE); } while (0) static void /* スレッド開始関数 */ tfunc(union sigval sv) { struct mq_attr attr; ssize_t nr; void *buf; mqd_t mqdes = *((mqd_t *) sv.sival_ptr); /* 最大メッセージサイズを決定し、 メッセージ受信用のバッファを確保する */ if (mq_getattr(mqdes, &attr) == -1) handle_error("mq_getattr"); buf = malloc(attr.mq_msgsize); if (buf == NULL) handle_error("malloc"); nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL); if (nr == -1) handle_error("mq_receive"); printf("Read %ld bytes from MQ\n", (long) nr); free(buf); exit(EXIT_SUCCESS); /* プロセスを終了する */ } int main(int argc, char *argv[]) { mqd_t mqdes; struct sigevent not; assert(argc == 2); mqdes = mq_open(argv[1], O_RDONLY); if (mqdes == (mqd_t) -1) handle_error("mq_open"); not.sigev_notify = SIGEV_THREAD; not.sigev_notify_function = tfunc; not.sigev_notify_attributes = NULL; not.sigev_value.sival_ptr = &mqdes; /* スレッド関数に渡す引き数 */ if (mq_notify(mqdes, ¬) == -1) handle_error("mq_notify"); pause(); /* プロセスはスレッド関数により終了される */ } 関連項目 mq_close(3), mq_getattr(3), mq_open(3), mq_receive(3), mq_send(3), mq_unlink(3), mq_overview(7) Linux 2009-01-27 MQ_NOTIFY(3)

MQ_NOTIFY(3) Linux Programmer’s Manual MQ_NOTIFY(3) NAME mq_notify - register for notification when a message is available SYNOPSIS #include mqd_t mq_notify(mqd_t mqdes, const struct sigevent *notification); Link with -lrt. DESCRIPTION mq_notify() allows the calling process to register or unregister for delivery of an asynchronous notification when a new message arrives on the empty message queue referred to by the descriptor mqdes. The notification argument is a pointer to a sigevent structure that is defined something like the following: union sigval { /* Data passed with notification */ int sival_int; /* Integer value */ void *sival_ptr; /* Pointer value */ }; struct sigevent { int sigev_notify; /* Notification method */ int sigev_signo; /* Notification signal */ union sigval sigev_value; /* Data passed with notification */ void (*sigev_notify_function) (union sigval); /* Function for thread notification */ void *sigev_notify_attributes; /* Thread function attributes */ }; If notification is a non-NULL pointer, then mq_notify() registers the calling process to receive message notification. The sigev_notify field of the sigevent to which notification points specifies how noti- fication is to be performed. This field has one of the following val- ues: SIGEV_NONE A "null" notification: the calling process is registered as the target for notification, but when a message arrives, no notifi- cation is sent. SIGEV_SIGNAL Notify the process by sending the signal specified in sigev_signo. If the signal is caught with a signal handler that was registered using the sigaction(2) SA_SIGINFO flag, then the following fields are set in the siginfo_t structure that is passed as the second argument of the handler: si_code is set to SI_MESGQ; si_signo is set to the signal number; si_value is set to the value specified in notification->sigev_value; si_pid is set to the PID of the process that sent the message; and si_uid is set to the real user ID of the sending process. The same information is available if the signal is accepted using sig- waitinfo(2). SIGEV_THREAD Deliver notification by invoking notifica- tion->sigev_notify_function as the start function of a new thread. The function is invoked with notification->sigev_value as its sole argument. If notification->sigev_notify_attributes is not NULL, then it should point to a pthread_attr_t structure that defines attributes for the thread (see pthread_attr_init(3)). Only one process can be registered to receive notification from a mes- sage queue. If notification is NULL, and the calling process is currently regis- tered to receive notifications for this message queue, then the regis- tration is removed; another process can then register to receive a mes- sage notification for this queue. Message notification only occurs when a new message arrives and the queue was previously empty. If the queue was not empty at the time mq_notify() was called, then a notification will only occur after the queue is emptied and a new message arrives. If another process or thread is waiting to read a message from an empty queue using mq_receive(3), then any message notification registration is ignored: the message is delivered to the process or thread calling mq_receive(3), and the message notification registration remains in effect. Notification occurs once: after a notification is delivered, the noti- fication registration is removed, and another process can register for message notification. If the notified process wishes to receive the next notification, it can use mq_notify() to request a further notifi- cation. This should be done before emptying all unread messages from the queue. (Placing the queue in non-blocking mode is useful for emp- tying the queue of messages without blocking once it is empty.) RETURN VALUE On success mq_notify() returns 0; on error, -1 is returned, with errno set to indicate the error. ERRORS EBADF The descriptor specified in mqdes is invalid. EBUSY Another process has already registered to receive notification for this message queue. EINVAL notification->sigev_notify is not one of the permitted values; or notification->sigev_notify is SIGEV_SIGNAL and notifica- tion->sigev_signo is not a valid signal number. ENOMEM Insufficient memory. POSIX.1-2008 says that an implementation may generate an EINVAL error if notification is NULL, and the caller is not currently registered to receive notifications for the queue mqdes. CONFORMING TO POSIX.1-2001. EXAMPLE The following program registers a notification request for the message queue named in its command-line argument. Notification is performed by creating a thread. The thread executes a function which reads one mes- sage from the queue and then terminates the process. #include #include #include #include #include #include #define handle_error(msg) \ do { perror(msg); exit(EXIT_FAILURE); } while (0) static void /* Thread start function */ tfunc(union sigval sv) { struct mq_attr attr; ssize_t nr; void *buf; mqd_t mqdes = *((mqd_t *) sv.sival_ptr); /* Determine max. msg size; allocate buffer to receive msg */ if (mq_getattr(mqdes, &attr) == -1) handle_error("mq_getattr"); buf = malloc(attr.mq_msgsize); if (buf == NULL) handle_error("malloc"); nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL); if (nr == -1) handle_error("mq_receive"); printf("Read %ld bytes from MQ\n", (long) nr); free(buf); exit(EXIT_SUCCESS); /* Terminate the process */ } int main(int argc, char *argv[]) { mqd_t mqdes; struct sigevent not; assert(argc == 2); mqdes = mq_open(argv[1], O_RDONLY); if (mqdes == (mqd_t) -1) handle_error("mq_open"); not.sigev_notify = SIGEV_THREAD; not.sigev_notify_function = tfunc; not.sigev_notify_attributes = NULL; not.sigev_value.sival_ptr = &mqdes; /* Arg. to thread func. */ if (mq_notify(mqdes, ¬) == -1) handle_error("mq_notify"); pause(); /* Process will be terminated by thread function */ } SEE ALSO mq_close(3), mq_getattr(3), mq_open(3), mq_receive(3), mq_send(3), mq_unlink(3), mq_overview(7) COLOPHON This page is part of release 3.22 of the Linux man-pages project. A description of the project, and information about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/. Linux 2009-03-31 MQ_NOTIFY(3)