名前

       msgrcv, msgsnd - System V メッセージキュー操作

書式

       #include <sys/types.h>
       #include <sys/ipc.h>
       #include <sys/msg.h>

       int msgsnd(int msqid, const void *msgp, size_t msgsz, int msgflg);

       ssize_t msgrcv(int msqid, void *msgp, size_t msgsz, long msgtyp,
                      int msgflg);

説明

       システムコール msgsnd()  と msgrcv()  はそれぞれ、 System V メッセージキューへのメッセージの送信と、 メッ
       セージの受信に使用される。呼び出し元プロセスは、 メッセージを送信するためにはメッセージキューに対する書き
       込み許可を、 メッセージを受信するためには読み出し許可を持っていなければならない。

       呼び出し元プロセスは以下に示す構造体を用意し、この構造体への ポインターを msgp 引き数として渡す。

           struct msgbuf {
               long mtype;       /* message type, must be > 0 */
               char mtext[1];    /* message data */
           };

       mtext  フィールドは配列  (または他の構造体) で、その大きさは 非負の整数である msgsz で指定される。 長さ 0
       のメッセージ (つまり mtext フィールドがないメッセージ) も認められている。 mtype  フィールドは厳密に正の整
       数でなければならない。  この値は、メッセージを受信するプロセスでメッセージを選択するために 使用される (下
       記の msgrcv()  の説明を参照のこと)。

   msgsnd()
       msgsnd()  システムコールは msgp 引き数で指定されたメッセージのコピーを msqid で指定された識別子を持つメッ
       セージキューへ追加する。

       キューに十分な空き容量がある場合、 msgsnd()  は直ちに成功する。  キューの容量は、メッセージキューのデータ
       構造体の msg_qbytes フィールドで制御される。 キュー作成時にこのフィールドは MSGMNB に初期化されるが、この
       制限は msgctl(2)  を使って変更できる。 次のいずれかの条件が成立する場合に、メッセージキューは一杯と判断さ
       れる。

       * 新しいメッセージをそのキューに追加すると、    そのキューの全バイト数がキューの最大サイズ    (msg_qbytes
         フィールド) を超過してしまう場合。

       * そのキューにもう一つメッセージを追加すると、 そのキューが全メッセージ数がキューの最大サイズ (msg_qbytes
         フィールド) を超過してしまう場合。 このチェックは、無限個の長さ 0  のメッセージをそのキューに追加するの
         を防ぐために必要である。  長さ 0 のメッセージはデータを含まないが、 (ロックされた) カーネルメモリーを消
         費するからである。

       そのキューに十分な領域がない場合、 デフォルトの動作では、 必要な領域ができるまで msgsnd() は停止  (block)
       する。 msgflg に IPC_NOWAIT が指定された場合、 msgsnd() はエラー EAGAIN で失敗する。

       停止している msgsnd()  は以下の場合にも失敗する。

       * キューが削除された。 この場合、 errno は EIDRM に設定される。

       * シグナルが捕捉された。  この場合、 errno は EINTR に設定される。 signal(7)  参照。 (msgsnd() は、たとえ
         シグナルハンドラーの設定時に SA_RESTART  を指定していたとしても、シグナルハンドラーによって割り込まれた
         後で 自動的に再スタートすることは決してない。)

       正常に終了した場合、メッセージキューのデータ構造体は以下のように 更新される:

              msg_lspid には呼び出し元プロセスのプロセス ID が設定される。

              msg_qnum は 1 増加する。

              msg_stime には現在時刻が設定される。

   msgrcv()
       msgrcv()  システムコールは msqid で指定されたキューからメッセージを削除し、 msgp で指定されたバッファーに
       そのメッセージを格納する。

       msgsz  引き数には msgp 引き数で指定された構造体の mtext メンバーの最大のバイト数を指定する。 メッセージの
       テキストの長さが msgsz より大きい場合の動作は、 msgflg に MSG_NOERROR  が指定されているかどうかで決まる。
       MSG_NOERROR   が指定されていれば、メッセージのテキストは切り詰められる   (切り捨てられた部分は失われる)。
       MSG_NOERROR が指定されていなければ、メッセージはキューから削除されず、 システムコールは  -1  を返して失敗
       し、 errno に E2BIG が設定される。

       MSG_COPY  が  msgflg  に指定されていない場合 (下記参照)、 msgtyp 引き数には要求するメッセージの型を指定す
       る。 型は以下のように指定する:

       * msgtyp が 0 ならば、キューの最初にあるメッセージが読み込まれる。

       * msgtyp が 0 より大きい場合、 msgflg に MSG_EXCEPT  が指定されていなければ、  msgtyp  型のキューの最初の
         メッセージが読み込まれる。  MSG_EXCEPT が指定された場合は、 msgtyp 型以外のキューの最初のメッセージが読
         み込まれる。

       * msgtyp が 0 より小さければ、 msgtyp  の絶対値以下で最も小さい型を持つキューの最初のメッセージが読み込ま
         れる。

       msgflg 引き数には、以下のフラグを任意の数だけ (0個も可)、これらの OR で指定する:

       IPC_NOWAIT
              キューに要求された型のメッセージがない場合には直ちに返る。   システムコールは失敗し、  errno  には
              ENOMSG が設定される。

       MSG_COPY (Linux 3.8 以降)
              キューの中で msgtyp で指定した位置にあるメッセージのコピーを、キューを変更せずに (非破壊的に) 取り
              出す (メッセージの位置は 0 から順番に番号が割り当てられる)。

              このフラグは IPC_NOWAIT と組み合わせて指定しなければならない。  その結果、指定した位置にメッセージ
              がなかった場合、呼び出しはエラー ENOMSG ですぐに失敗する。 MSG_COPY と MSG_EXCEPT は msgtyp の意味
              を相容れない方法で使用するため、この二つのフラグの両方を msgtyp に指定することはできない。

              MSG_COPY フラグは、 カーネルのチェックポイント復元 (checkpoint-restore) 機能の実装のために追加され
              た。 このフラグはカーネルが CONFIG_CHECKPOINT_RESTORE オプションを有効にして作成された場合にのみ利
              用できる。

       MSG_EXCEPT
              0 より大きな msgtyp と一緒に使用して、 msgtyp 以外のキューの最初のメッセージを読み込む。

       MSG_NOERROR
              msgsz バイトよりも長かった場合はメッセージのテキストを切り詰める。

       要求された型のメッセージが存在せず、  msgflg に IPC_NOWAIT が指定されていなかった場合、呼び出し元プロセス
       は 以下のいずれかの状況になるまで停止 (block) される:

       * 要求している型のメッセージがキューへ入れられた。

       * メッセージキューがシステムから削除された。 この場合、システムコールは失敗し、 errno に EIDRM が設定され
         る。

       * 呼び出し元プロセスがシグナルを捕獲した。 この場合、システムコールは失敗し、 errno に  EINTR  が設定され
         る。  (msgrcv()  は、たとえシグナルハンドラーの設定時に SA_RESTART を指定していたとしても、シグナルハン
         ドラーによって割り込まれた後で 自動的に再スタートすることは決してない。)

       正常に終了した場合、メッセージキューのデータ構造体は以下のように 更新される:

              msg_lrpid には呼び出し元プロセスのプロセス ID が設定される。

              msg_qnum は 1 減算される。

              msg_rtime には現在の時刻が設定される。

返り値

       失敗した場合は、どちらの関数も -1 を返し、エラーを errno に表示する。成功した場合、 msgsnd()  は  0  を返
       し、 msgrcv()  は mtext 配列に実際にコピーしたバイト数を返す。

エラー

       msgsnd()  が失敗した場合、 errno に以下の値のいずれかが設定される:

       EACCES 呼び出し元プロセスにはメッセージキューに対する書き込み許可がなく、  CAP_IPC_OWNER ケーパビリティも
              ない。

       EAGAIN msg_qbytes がキューの制限を超えていたため、メッセージを送ることができず、かつ msgflg に IPC_NOWAIT
              が指定されていた。

       EFAULT msgp が指しているアドレスがアクセス可能でない。

       EIDRM  メッセージキューが削除された。

       EINTR  メッセージキューが要求した条件を満たすまで停止している時に、 プロセスがシグナルを捕獲した。

       EINVAL msqid が不適切な値であるか、 mtype が正の値でないか、 msgsz が不適切な値 (0 以下か、システムで決ま
              る値 MSGMAX よりも大きい値) である。

       ENOMEM msgp が指すメッセージのコピーを作成するのに十分なメモリーがシステムに存在しない。

       msgrcv()  が失敗した場合には errno に以下の値のいずれかが設定される:

       E2BIG  メッセージのテキストの長さが msgsz よりも大きく、 msgflg に MSG_NOERROR が設定されていなかった。

       EACCES 呼び出し元プロセスにはメッセージキューに対する読み込み許可がなく、 CAP_IPC_OWNER  ケーパビリティも
              ない。

       EAGAIN キューにはメッセージがなく、 msgflg に IPC_NOWAIT が指定された。

       EFAULT msgp が指しているアドレスがアクセス可能でない。

       EIDRM  メッセージを受信するためにプロセスが停止している間に、 メッセージキューが削除された。

       EINTR  メッセージを受けるためにプロセスが停止している間に、  プロセスがシグナルを捕獲した。 signal(7)  参
              照。

       EINVAL msgqid が不正か、 msgsz が 0 より小さい。

       EINVAL (Linux 3.14 以降)
              msgflg に MSG_COPY が指定されたが、 IPC_NOWAIT が指定されていない。

       EINVAL (Linux 3.14 以降)
              msgflg に MSG_COPY と MSG_EXCEPT の両方が指定された。

       ENOMSG msgflg に IPC_NOWAIT  が設定されており、  メッセージキューに要求された型のメッセージが存在しなかっ
              た。

       ENOMSG IPC_NOWAIT と MSG_COPY が msgflg に指定されたが、 キューには msgtyp 未満のメッセージしか入っていな
              かった。

       ENOSYS (Linux 3.8 以降)
              msgflg に MSG_COPY が指定されたが、カーネルが CONFIG_CHECKPOINT_RESTORE なしで作成されている。

準拠

       SVr4, POSIX.1-2001.

       フラグ MSG_EXCEPT と MSG_COPY は Linux 固有である。 これらの定義を得るには、機能検査マクロ _GNU_SOURCE を
       定義する。

注意

       Linux や POSIX の全てのバージョンでは、 <sys/types.h> と <sys/ipc.h> のインクルードは必要ない。しかしなが
       ら、いくつかの古い実装ではこれらのヘッダーファイルのインクルードが必要であり、   SVID  でもこれらのインク
       ルードをするように記載されている。このような古いシステムへの移植性を意図したアプリケーションではこれらの
       ファイルをインクルードする必要があるかもしれない。

       msgp 引き数は、 glibc 2.0 と 2.1 では struct msgbuf * と宣言されている。glibc  2.2  以降では、  SUSv2  と
       SUSv3 の要求通り、void * と宣言されている。

       以下は msgsnd システムコールに影響するシステム制限である:

       MSGMAX メッセージのテキストの最大サイズ: 8192 バイト (Linux では、この制限値は /proc/sys/kernel/msgmax 経
              由で読み出したり変更したりできる)。

       MSGMNB バイト単位でのメッセージキューのデフォルトの最大サイズ  : 16384 バイト。 (Linux では、この制限値は
              /proc/sys/kernel/msgmnb 経由で読み出したり変更したりできる)。 特権プロセス  (Linux  ではケーパビリ
              ティ  CAP_SYS_RESOURCE  を持ったプロセス) は msgctl(2)  システムコールでメッセージキューのサイズを
              MSGMNB よりも大きい値に増やすことができる。

       現在の実装では、システム全体のメッセージヘッダーの上限数 (MSGTQL)  と、システム全体のメッセージプールの最
       大バイト数 (MSGPOOL)  に関して実装依存の制限はない。

バグ

       Linux 3.13 以前では、 msgrcv() の呼び出しで MSG_COPY フラグは指定されたが  IPC_NOWAIT  は指定されず、かつ
       メッセージキューに  msgtyp 未満のメッセージしかない場合に、 msgrcv() の呼び出しはキューに次のメッセージが
       書き込まれるまで停止していた。   新しいメッセージが書き込まれた時点で、    そのメッセージが指定された位置
       msgtyp  かどうかに関わらず、 msgrcv() の呼び出しは新たに書き込まれたメッセージのコピーを返していた。 この
       バグは Linux ３．１４で修正された。

       msg_copy に MSG_COPY と MSG_EXCEPT  の両方を指定するのは、論理的なエラーである  (なぜならこれらのフラグは
       msgtyp  を別の意味で解釈するからである)。 Linux 3.13 以前では、msgrcv() がこのエラーを検出しなかった。 こ
       のバグは Linux 3.14 で修正された。

関連項目

       msgctl(2), msgget(2), capabilities(7), mq_overview(7), svipc(7)

この文書について

       この man ページは Linux man-pages プロジェクトのリリース 3.79 の一部 である。プロジェクトの説明とバグ報告
       に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。

Linux                                              2014-08-19                                           MSGOP(2)