名称

mq_receive, mq_timedreceive — メッセージキューからメッセージを受信する (リアルタイム)

ライブラリ

POSIX Real-time Library (librt, -lrt)

書式

#include < mqueue.h>

ssize_t
mq_receive( mqd_t mqdes, char *msg_ptr, size_t msg_len, unsigned *msg_prio);

ssize_t
mq_timedreceive( mqd_t mqdes, char *msg_ptr, size_t msg_len, unsigned *msg_prio, const struct timespec *abs_timeout);

解説

mq_receive() システムコールは、 mqdes によって指定されたメッセージキューから最優先で最も古いメッセージを受信します。 msg_len 引数によって指定されたバッファのバイト単位のサイズがメッセージキューの mq_msgsize 属性未満であるなら、システムコールは、失敗して、エラーを返します。そうでなければ、選択されたメッセージは、キューから削除され、 msg_ptr 引数によって指されたバッファにコピーされます。

引数 msg_prio が NULL でないなら、選択されたメッセージの優先順位は、 msg_prio によって参照された位置に格納されます。指定されたメッセージキューが空で、 mqdes に関連しているメッセージキューの記述に O_NONBLOCK が設定されたいないなら、メッセージがメッセージキューでエンキューされる (キューに入れられる) まで、または mq_receive() がシグナルによって割り込まれるまで、 mq_receive() は、ブロックされます。 2 つ以上のスレッドが、メッセージが空のキューに到達するとき、メッセージの受信をウェート (待つ) し、Priority Scheduling (優先スケジューリング) オプションがサポートされているなら、メッセージを受信するために、最も長い間ウェートしている最も高い優先順序のスレッドが選択されます。そうでなければ、どのウェートしているスレッドがメッセージを受信するかは、不特定です。指定されたメッセージキューが空であり、 O_NONBLOCK が mqdes に関連しているメッセージキュー記述で設定されているなら、メッセージは、キューから削除されないで、 mq_receive() は、エラーを返します。

mq_timedreceive() システムコールは、 mq_receive() システムコールによって説明されているように mqdes によって指定されているメッセージキューからの最も高い優先順序の最も古いメッセージを受信します。しかしながら、メッセージキューが mq_open() システムコールによってオープンされるとき、 O_NONBLOCK が指定されず、メッセージが受信を満たすためのキューに存在しないなら、そのようなメッセージのためのウェートは、指定されたタイムアウトの期限が切れるとき、終了されます。 O_NONBLOCK が設定されるなら、このシステムコールは mq_receive() と同等です。

abs_timeout によって指定された絶対的な時間が経過するとき、タイムアウトが基づいている (すなわち、そのクロックの値が、 abs_timeout と等しいか、または超えるとき) クロックによって測定されるか、または abs_timeout によって指定された絶対的な時間が呼び出し時点で既に過ぎているなら、タイムアウトは期限が切れます。

タイムアウトは CLOCK_REALTIME クロックに基づいています。

戻り値

成功して終了ときに、 mq_receive() と mq_timedreceive() システムコールは、選択されたメッセージの長さをバイト単位で返し、メッセージは、キューから削除されます。そうでなければ、メッセージは、キューから削除されず、システムコールは-1 の値を返し、グローバル変数 errno にエラーを示す値が設定されます。

エラー

mq_receive() と mq_timedreceive() システムコールは、次の場合に失敗します:

[ EAGAIN]

O_NONBLOCK フラグは、 mqdes に関連しているメッセージキュー記述で設定され、指定されたメッセージキューは空です。

[ EBADF]

mqdes 引数が、読み込み用にオープンしている有効なメッセージキュー記述子ではありません。

[ EMSGSIZE]

指定されたメッセージバッファサイズ msg_len が、メッセージキューのメッセージサイズ属性未満です。

[ EINTR]

mq_receive() または mq_timedreceive() 操作がシグナルによって割り込まれました。

[ EINVAL]

プロセスまたはスレッドがブロックされており、 abs_timeout パラメータに、0 未満か、または 10 億以上のナノ秒フールド値が指定されました。

[ ETIMEDOUT]

メッセージキューがオープンされたとき、 O_NONBLOCK フラグが設定されていませんでしたが、指定されたタイムアウトの期限が切れる前にメッセージがキューに到着しませんでした。

関連項目

mq_open(2), mq_send(2), mq_timedsend(2)

規格

mq_receive() と mq_timedreceive() システムコールは、 IEEE Std 1003.1-2004 (“POSIX.1”) に適合しています。

歴史

POSIX メッセージキューのサポートは FreeBSD 7.0 ではじめて登場しました。

COPYRIGHT

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.