MSGOP(2)

名前
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
    The calling process does not have write permission on the message queue, and does not have the CAP_IPC_OWNER capability in the user namespace that governs its IPC namespace.

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
    The calling process does not have read permission on the message queue, and does not have the CAP_IPC_OWNER capability in the user namespace that governs its IPC namespace.

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

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

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

EINVAL
    msgid が不正か、 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 と IPC_NOWAIT の両方が指定されたが、カーネルが CONFIG_CHECKPOINT_RESTORE なしで作成されている。

準拠
POSIX.1-2001, POSIX.1-2008, SVr4.

フラグ 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
    Maximum size of a message text, in bytes (default value: 8192 bytes). On Linux, this limit can be read and modified via /proc/sys/kernel/msgmax.

MSGMNB
    Maximum number of bytes that can be held in a message queue (default value: 16384 bytes). On Linux, this limit can be read and modified via /proc/sys/kernel/msgmnb. A privileged process (Linux: a process with the CAP_SYS_RESOURCE capability) can increase the size of a message queue beyond MSGMNB using the msgctl(2) IPC_SET operation.

現在の実装では、システム全体のメッセージヘッダーの上限数 (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 で修正された。

例
The program below demonstrates the use of msgsnd() and msgrcv().

The example program is first run with the -s option to send a message and then run again with the -r option to receive a message.

The following shell session shows a sample run of the program:

    $ ./a.out -s
    sent: a message at Wed Mar  4 16:25:45 2015

    $ ./a.out -r
    message received: a message at Wed Mar  4 16:25:45 2015

  プログラムのソース
    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include <time.h>
    #include <unistd.h>
    #include <errno.h>
    #include <sys/types.h>
    #include <sys/ipc.h>
    #include <sys/msg.h>

    struct msgbuf {
        long mtype;
        char mtext[80];
    };

    static void
    usage(char *prog_name, char *msg)
    {
        if (msg != NULL)
            fputs(msg, stderr);

        fprintf(stderr, "Usage: %s [options]\n", prog_name);
        fprintf(stderr, "Options are:\n");
        fprintf(stderr, "-s        send message using msgsnd()\n");
        fprintf(stderr, "-r        read message using msgrcv()\n");
        fprintf(stderr, "-t        message type (default is 1)\n");
        fprintf(stderr, "-k        message queue key (default is 1234)\n");
        exit(EXIT_FAILURE);
    }

    static void
    send_msg(int qid, int msgtype)
    {
        struct msgbuf msg;
        time_t t;

        msg.mtype = msgtype;

        time(&t);
        snprintf(msg.mtext, sizeof(msg.mtext), "a message at %s",
                ctime(&t));

        if (msgsnd(qid, &msg, sizeof(msg.mtext),
                    IPC_NOWAIT) == -1) {
            perror("msgsnd error");
            exit(EXIT_FAILURE);
        }
        printf("sent: %s\n", msg.mtext);
    }

    static void
    get_msg(int qid, int msgtype)
    {
        struct msgbuf msg;

        if (msgrcv(qid, &msg, sizeof(msg.mtext), msgtype,
                   MSG_NOERROR | IPC_NOWAIT) == -1) {
            if (errno != ENOMSG) {
                perror("msgrcv");
                exit(EXIT_FAILURE);
            }
            printf("No message available for msgrcv()\n");
        } else
            printf("message received: %s\n", msg.mtext);
    }

    int
    main(int argc, char *argv[])
    {
        int qid, opt;
        int mode = 0;               /* 1 = send, 2 = receive */
        int msgtype = 1;
        int msgkey = 1234;

        while ((opt = getopt(argc, argv, "srt:k:")) != -1) {
            switch (opt) {
            case 's':
                mode = 1;
                break;
            case 'r':
                mode = 2;
                break;
            case 't':
                msgtype = atoi(optarg);
                if (msgtype <= 0)
                    usage(argv[0], "-t option must be greater than 0\n");
                break;
            case 'k':
                msgkey = atoi(optarg);
                break;
            default:
                usage(argv[0], "Unrecognized option\n");
            }
        }

        if (mode == 0)
            usage(argv[0], "must use either -s or -r option\n");

        qid = msgget(msgkey, IPC_CREAT | 0666);

        if (qid == -1) {
            perror("msgget");
            exit(EXIT_FAILURE);
        }

        if (mode == 2)
            get_msg(qid, msgtype);
        else
            send_msg(qid, msgtype);

        exit(EXIT_SUCCESS);
    }

関連項目
msgctl(2), msgget(2), capabilities(7), mq_overview(7), sysvipc(7)

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