Provided by: manpages-ja-dev_0.5.0.0.20221215+dfsg-1_all bug

名前

       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;   /* Ownership and permissions */
               time_t          msg_stime;  /* Time of last msgsnd(2) */
               time_t          msg_rtime;  /* Time of last msgrcv(2) */
               time_t          msg_ctime;  /* Time of creation or last
                                              modification by msgctl() */
               unsigned long   msg_cbytes; /* # of bytes in queue */
               msgqnum_t       msg_qnum;   /* # number of messages in queue */
               msglen_t        msg_qbytes; /* Maximum # of bytes in queue */
               pid_t           msg_lspid;  /* PID of last msgsnd(2) */
               pid_t           msg_lrpid;  /* PID of last msgrcv(2) */
           };

       msgid_ds 構造体のフィールドは以下の通りである:

       msg_perm   This is an ipc_perm structure (see below) that specifies the access permissions on the message
                  queue.

       msg_stime  最後の msgsnd(2) システムコールの時刻。

       msg_rtime  最後の msgrcv(2) システムコールの時刻。

       msg_ctime  Time of creation of queue or time of last msgctl()  IPC_SET operation.

       msg_cbytes Number  of  bytes in all messages currently on the message queue.  This is a nonstandard Linux
                  extension that is not specified in POSIX.

       msg_qnum   Number of messages currently on the message queue.

       msg_qbytes Maximum number of bytes of message text allowed on the message queue.

       msg_lspid  最後の msgsnd(2) システムコールを実行したプロセスの ID。

       msg_lrpid  最後の msgrcv(2) システムコールを実行したプロセスの ID。

       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;       /* シーケンス番号 */
           };

       The least significant 9 bits of the mode field of the ipc_perm structure define  the  access  permissions
       for the message queue.  The permission bits are as follows:

       0400   ユーザーによる読み出し
       0200   ユーザーによる書き込み
       0040   グループによる読み出し
       0020   グループによる書き込み
       0004   他人 (others) による読み出し
       0002   他人 (others) による書き込み

       ビット 0100, 0010, 0001 (実行ビット) をシステムは使用しない。

       cmd として有効な値は:

       IPC_STAT
              msqid  に関連づけられたメッセージキューデータ構造体から、ポインター buf が指し示す msqid_ds 構造体
              に情報をコピーする。 呼び出し側はメッセージキューに対する読み込み許可を持っていなければならない。

       IPC_SET
              Write the values of some members of the msqid_ds structure pointed to by buf to  the  kernel  data
              structure associated with this message queue, updating also its msg_ctime member.

              The  following  members  of the structure are updated: msg_qbytes, msg_perm.uid, msg_perm.gid, and
              (the least significant 9 bits of) msg_perm.mode.

              The effective UID of  the  calling  process  must  match  the  owner  (msg_perm.uid)   or  creator
              (msg_perm.cuid)   of  the  message queue, or the caller must be privileged.  Appropriate privilege
              (Linux: the CAP_SYS_RESOURCE capability) is required to raise  the  msg_qbytes  value  beyond  the
              system parameter MSGMNB.

       IPC_RMID
              メッセージキューをただちに削除する。  同時にその構造体の読み書きの待ち状態にあったプロセスに通知す
              る (エラーが返り、 errnoEIDRM  に設定される)。  呼び出したプロセスが適切な特権を持っているか、
              呼び出したプロセスの実効ユーザー  ID がメッセージキューの作成者か 所有者の実効ユーザー ID でなけれ
              ばならない。この場合、 msgctl() の第 3 引数は無視される。

       IPC_INFO (Linux 固有)
              システム全体でのメッセージキューの制限とパラメーターに関する情報を、  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 msgseg;
                                   /* 最大セグメント数; カーネル内では未使用 */
                  };

              設定 msgmni , msgmax , msgmnb/proc  にある同じ名前のファイル経由で変更可能である。  詳しくは
              proc(5)  を参照。

       MSG_INFO (Linux 固有)
              IPC_INFO  のときと同じ情報を格納した  msginfo  構造体を返す。 但し、以下のフィールドにはメッセージ
              キューが 消費しているシステム資源に関する情報が格納される点が異なる。 msgpool フィールドは現在シス
              テム上に存在するメッセージキューの数を返す。 msgmap フィールドはシステム上の全てのキューに入ってい
              るメッセージ総数を返す。 msgtql フィールドはシステム上の全てのキューに入っている全メッセージの  総
              バイト数を返す。

       MSG_STAT (Linux 固有)
              IPC_STAT  と同じく msqid_ds 構造体を返す。 但し、 msqid 引数は、キュー識別子ではなく、システム上の
              全てのメッセージキュー に関する情報を管理するカーネルの内部配列へのインデックスである。

       MSG_STAT_ANY (Linux 固有, Linux 4.17 以降)
              Return a msqid_ds structure as for MSG_STAT.  However,  msg_perm.mode  is  not  checked  for  read
              access  for  msqid  meaning  that  any  user  can employ this operation (just as any user may read
              /proc/sysvipc/msg to obtain the same information).

返り値

       On success, IPC_STAT, IPC_SET, and IPC_RMID return  0.   A  successful  IPC_INFO  or  MSG_INFO  operation
       returns  the  index  of the highest used entry in the kernel's internal array recording information about
       all message queues.  (This information can be used with repeated MSG_STAT or MSG_STAT_ANY  operations  to
       obtain  information  about  all  queues  on the system.)  A successful MSG_STAT or MSG_STAT_ANY operation
       returns the identifier of the queue whose index was given in msqid.

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

エラー

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

       EACCES The argument cmd is equal to IPC_STAT or MSG_STAT, but the calling  process  does  not  have  read
              permission  on the message queue msqid, and does not have the CAP_IPC_OWNER capability in the user
              namespace that governs its IPC namespace.

       EFAULT 引数 cmdIPC_SETIPC_STAT で、ポインター buf で指されているアドレスがアクセス可能でない。

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

       EINVAL cmd または msqid に不正な値が設定された。 もしくは、 MSG_STAT 操作の場合に、 msqid  で指定されたイ
              ンデックス値が現在未使用の配列のスロットを参照いていた。

       EPERM  引数 cmdIPC_SETIPC_RMID であるが、呼び出したプロセスの実効ユーザー ID がメッセージキューの
              (msg_perm.cuid として見つかる) 作成者 と (msg_perm.uid として見つかる) 所有者のいずれでもなく、 か
              つ呼び出し者に特権がない (Linux では CAP_SYS_ADMIN ケーパビリティがない)。

       EPERM  IPC_SETmsg_qbytes をシステムパラメーター MSGMNB より大きな値に設定しようとしたが、呼び出し元が
              特権を持っていなかった (Linux では、 CAP_SYS_RESOURCE ケーパビリティを持っていなかった)。

準拠

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

注意

       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), sysvipc(7)

この文書について

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