DOKK / manpages / debian 11 / manpages-ja-dev / msgctl.2.ja
MSGCTL(2) Linux Programmer's Manual MSGCTL(2)

名前

msgctl - System V メッセージ制御操作

書式

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>
int msgctl(int msqid, int cmd, struct msqid_ds *buf);

説明

msgctl() はメッセージキュー識別子 msqid で指定された System V メッセージキュー (message queue) に対して cmd で指定された制御操作を行なう。

msqid_ds データ構造体は <sys/msg.h> で以下のように定義されている:



struct msqid_ds {


    struct ipc_perm msg_perm;     /* 所有権と許可 */


    time_t          msg_stime;    /* 最後の msgsnd(2) の時刻 */


    time_t          msg_rtime;    /* 最後の msgrcv(2) の時刻 */


    time_t          msg_ctime;    /* 最後に変更が行われた時刻 */


    unsigned long   __msg_cbytes; /* キューにある現在のバイト数


                                     (非標準) */


    msgqnum_t       msg_qnum;     /* キューにある現在入っている


                                     メッセージの数 */


    msglen_t        msg_qbytes;   /* キューに許可されている


                                     最大バイト数 */


    pid_t           msg_lspid;    /* 最後の msgsnd(2) の PID */


    pid_t           msg_lrpid;    /* 最後の msgrcv(2) の PID */
};

ipc_perm 構造体は以下のように定義されている (強調されたフィールドは IPC_SET を使って設定可能である):



struct ipc_perm {


    key_t          __key;       /* msgget(2) に与えるキー */


    uid_t          uid;         /* 所有者の実効 UID */


    gid_t          gid;         /* 所有者の実効 GID */


    uid_t          cuid;        /* 作成者の実効 UID */


    gid_t          cgid;        /* 作成者の実効 GID */


    unsigned short mode;        /* 許可 */


    unsigned short __seq;       /* シーケンス番号 */
};

cmd として有効な値は:

msqid に関連づけられたメッセージキューデータ構造体から、ポインター buf が指し示す msqid_ds 構造体に情報をコピーする。 呼び出し側はメッセージキューに対する読み込み許可を持っていなければならない。
ポインター buf が指し示す msqid_ds 構造体のメンバーの値を、メッセージキューに関連づけられた カーネルデータ構造体に書き込み、 msg_ctime メンバーも更新する。 構造体のメンバーのうち、更新されるものを以下に示す: msg_qbytes, msg_perm.uid, msg_perm.gid, msg_perm.mode (の下位 9 ビット)。 呼び出したプロセスの実効ユーザー ID が、メッセージキューの所有者 (msg_perm.uid) または作成者 (msg_perm.cuid) と一致するか、呼び出し元が特権を持たなければならない。 msg_qbytes をシステムパラメーターの MSGMNB を超えて設定するには、適切な特権 (Linux では CAP_SYS_RESOURCE ケーパビリティ (capability)) が必要である。
メッセージキューをただちに削除する。 同時にその構造体の読み書きの待ち状態にあったプロセスに通知する (エラーが返り、 errno が EIDRM に設定される)。 呼び出したプロセスが適切な特権を持っているか、 呼び出したプロセスの実効ユーザー ID がメッセージキューの作成者か 所有者の実効ユーザー ID でなければならない。この場合、 msgctl() の第 3 引き数は無視される。
システム全体でのメッセージキューの制限とパラメーターに関する情報を、 buf が指す構造体に入れて返す。 この構造体は msginfo 型である (そのためキャストが必要である)。 msginfo は _GNU_SOURCE 機能検査マクロが定義された場合に <sys/msg.h> で以下のように定義される: 


struct msginfo {


    int msgpool; /* メッセージデータの保持に使用される


                    バッファープールの大きさ (1024 バイト単位);


                    カーネル内では未使用 */


    int msgmap;  /* メッセージマップの最大エントリー数;


                    カーネル内では未使用 */


    int msgmax;  /* 一つのメッセージに書き込み可能な


                    最大バイト数 */


    int msgmnb;  /* 一つのキューに書き込み可能な最大バイト数;


                    (msgget(2) での) キュー作成中の msg_qbytes


                    の初期化に使用される */


    int msgmni;  /* メッセージキューの数の最大値 */


    int msgssz;  /* メッセージセグメントのサイズ;


                    カーネル内では未使用 */


    int msgtql;  /* システム上の全キューの最大メッセージ数;


                    カーネル内では未使用 */


    unsigned short int msgseg;


                 /* 最大セグメント数; カーネル内では未使用 */
};
設定 msgmni , msgmax , msgmnb は /proc にある同じ名前のファイル経由で変更可能である。 詳しくは proc(5) を参照。
IPC_INFO のときと同じ情報を格納した msginfo 構造体を返す。 但し、以下のフィールドにはメッセージキューが 消費しているシステム資源に関する情報が格納される点が異なる。 msgpool フィールドは現在システム上に存在するメッセージキューの数を返す。 msgmap フィールドはシステム上の全てのキューに入っているメッセージ総数を返す。 msgtql フィールドはシステム上の全てのキューに入っている全メッセージの 総バイト数を返す。
IPC_STAT と同じく msqid_ds 構造体を返す。 但し、 msqid 引き数は、キュー識別子ではなく、システム上の全てのメッセージキュー に関する情報を管理するカーネルの内部配列へのインデックスである。

返り値

成功すると、 IPC_STAT, IPC_SET, IPC_RMID は 0 を返す。 IPC_INFO と MSG_INFO 操作は、成功すると、全てのメッセージキューに関する情報を 管理しているカーネルの内部配列の使用中エントリーのインデックスの うち最大値を返す (この情報は、システムの全てのメッセージキューに関する情報を 取得するために、 MSG_STAT 操作を繰り返し実行する際に使用できる)。 MSG_STAT 操作は、成功すると、 msqid で指定されたインデックスを持つメッセージキューの識別子を返す。

エラーの場合は -1 を返し、 errno を適切に設定する。

エラー

失敗した場合、 errno は以下の値の中のどれか一つに設定される:

引き数 cmd が IPC_STAT または MSG_STAT に等しいが、呼び出したプロセスがメッセージキュー msqid に対する読み込み許可を持っておらず、かつ CAP_IPC_OWNER ケーパビリティを持っていない。
引き数 cmd が IPC_SET か IPC_STAT で、ポインター buf で指されているアドレスがアクセス可能でない。
メッセージキューが削除された。
cmd または msqid に不正な値が設定された。 もしくは、 MSG_STAT 操作の場合に、 msqid で指定されたインデックス値が現在未使用の配列のスロットを参照いていた。
引き数 cmd が IPC_SET か IPC_RMID であるが、呼び出したプロセスの実効ユーザー ID がメッセージキューの (msg_perm.cuid として見つかる) 作成者 と (msg_perm.uid として見つかる) 所有者のいずれでもなく、 かつ呼び出し者に特権がない (Linux では CAP_SYS_ADMIN ケーパビリティがない)。
IPC_SET で msg_qbytes をシステムパラメーター MSGMNB より大きな値に設定しようとしたが、呼び出し元が特権を持っていなかった (Linux では、 CAP_SYS_RESOURCE ケーパビリティを持っていなかった)。

準拠

SVr4, POSIX.1-2001.

注意

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

IPC_INFO, MSG_STAT, MSG_INFO 操作は、 ipcs(1) プログラムで割り当て済の資源に関する情報を提供するために 使用されている。将来、これらの操作は変更されたり、 /proc ファイルシステムのインターフェースに移動されるかもしれない。

struct msqid_ds 内の多くのフィールドは、 Linux 2.2 では short だったが、Linux 2.4 では long になった。 この利点を生かすには、glibc-2.1.91 以降の環境下で 再コンパイルすれば十分である。 (カーネルは新しい形式の呼び出しと古い形式の呼び出しを cmd 内の IPC_64 フラグで区別する。)

関連項目

msgget(2), msgrcv(2), msgsnd(2), capabilities(7), mq_overview(7), svipc(7)

この文書について

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

2014-02-24 Linux