MSGOP

Section: Linux Programmer's Manual (2)
Updated: 2020-11-01
Index JM Home Page roff page
 

名前

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) する。 msgflgIPC_NOWAIT が指定された場合、 msgsnd() はエラー EAGAIN で失敗する。

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

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

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

msg_lspid には呼び出し元プロセスのプロセス ID が設定される。
msg_qnum は 1 増加する。
msg_stime には現在時刻が設定される。
 

msgrcv()

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

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

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

msgtyp が 0 ならば、キューの最初にあるメッセージが読み込まれる。
msgtyp が 0 より大きい場合、 msgflgMSG_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_COPYMSG_EXCEPTmsgtyp の意味を相容れない方法で使用するため、この二つのフラグの両方を msgtyp に指定することはできない。
MSG_COPY フラグは、 カーネルのチェックポイント復元 (checkpoint-restore) 機能の実装のために追加された。 このフラグはカーネルが CONFIG_CHECKPOINT_RESTORE オプションを有効にして作成された場合にのみ利用できる。
MSG_EXCEPT
0 より大きな msgtyp と一緒に使用して、 msgtyp 以外のキューの最初のメッセージを読み込む。
MSG_NOERROR
msgsz バイトよりも長かった場合はメッセージのテキストを切り詰める。

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

要求している型のメッセージがキューへ入れられた。
メッセージキューがシステムから削除された。 この場合、システムコールは失敗し、 errnoEIDRM が設定される。
呼び出し元プロセスがシグナルを捕獲した。 この場合、システムコールは失敗し、 errnoEINTR が設定される。 (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 がキューの制限を超えていたため、メッセージを送ることができず、かつ msgflgIPC_NOWAIT が指定されていた。
EFAULT
msgp が指しているアドレスがアクセス可能でない。
EIDRM
メッセージキューが削除された。
EINTR
メッセージキューが要求した条件を満たすまで停止している時に、 プロセスがシグナルを捕獲した。
EINVAL
msqid が不適切な値であるか、 mtype が正の値でないか、 msgsz が不適切な値 (0 以下か、システムで決まる値 MSGMAX よりも大きい値) である。
ENOMEM
msgp が指すメッセージのコピーを作成するのに十分なメモリーがシステムに存在しない。

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

E2BIG
メッセージのテキストの長さが msgsz よりも大きく、 msgflgMSG_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 以降)
msgflgMSG_COPY が指定されたが、 IPC_NOWAIT が指定されていない。
EINVAL (Linux 3.14 以降)
msgflgMSG_COPYMSG_EXCEPT の両方が指定された。
ENOMSG
msgflgIPC_NOWAIT が設定されており、 メッセージキューに要求された型のメッセージが存在しなかった。
ENOMSG
IPC_NOWAITMSG_COPYmsgflg に指定されたが、 キューには msgtyp 未満のメッセージしか入っていなかった。
ENOSYS (Linux 3.8 以降)
msgflgMSG_COPYIPC_NOWAIT の両方が指定されたが、カーネルが CONFIG_CHECKPOINT_RESTORE なしで作成されている。
 

準拠

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

フラグ MSG_EXCEPTMSG_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 3.14で修正された。

msg_copyMSG_COPYMSG_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/ に書かれている。


 

Index

名前
書式
説明
msgsnd()
msgrcv()
返り値
エラー
準拠
注意
バグ
プログラムのソース
関連項目
この文書について

This document was created by man2html, using the manual pages.
Time: 16:46:42 GMT, November 24, 2023