.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
.\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
.\" Modified Sun Feb 18 01:59:29 2001 by Andries E. Brouwer <aeb@cwi.nl>
.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
.\"     Added notes on CAP_IPC_OWNER requirement
.\" Modified, 17 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com>
.\"     Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID
.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
.\"	Language and formatting clean-ups
.\"	Added msqid_ds and ipc_perm structure definitions
.\" 2005-08-02, mtk: Added IPC_INFO, MSG_INFO, MSG_STAT descriptions
.\" 2018-03-20, dbueso: Added MSG_STAT_ANY description.
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.\"
.\" Japanese Version Copyright (c) 1997 HANATAKA Shinya
.\"         all rights reserved.
.\" Translated 1997-02-23, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
.\" Updated & Modified 2001-06-04, Yuichi SATO <ysato@h4.dion.ne.jp>
.\" Updated & Modified 2002-07-06, Yuichi SATO
.\" Updated & Modified 2004-12-31, Yuichi SATO <ysato444@yahoo.co.jp>
.\" Updated & Modified 2005-10-10, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
.\" Updated 2013-05-01, Akihiro MOTOKI <amotoki@gmail.com>
.\"
.TH MSGCTL 2 2020\-11\-01 Linux "Linux Programmer's Manual"
.SH 名前
msgctl \- System V メッセージ制御操作
.SH 書式
.nf
\fB#include <sys/types.h>\fP
\fB#include <sys/ipc.h>\fP
\fB#include <sys/msg.h>\fP
.PP
\fBint msgctl(int \fP\fImsqid\fP\fB, int \fP\fIcmd\fP\fB, struct msqid_ds *\fP\fIbuf\fP\fB);\fP
.fi
.SH 説明
\fBmsgctl\fP()  はメッセージキュー識別子 \fImsqid\fP で指定された System\ V メッセージキュー (message queue)
に対して \fIcmd\fP で指定された制御操作を行なう。
.PP
\fImsqid_ds\fP データ構造体は \fI<sys/msg.h>\fP で以下のように定義されている:
.PP
.in +4n
.EX
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) */
};
.EE
.in
.PP
\fImsgid_ds\fP 構造体のフィールドは以下の通りである:
.TP  11
\fImsg_perm\fP
This is an \fIipc_perm\fP structure (see below) that specifies the access
permissions on the message queue.
.TP 
\fImsg_stime\fP
最後の \fBmsgsnd\fP(2) システムコールの時刻。
.TP 
\fImsg_rtime\fP
最後の \fBmsgrcv\fP(2) システムコールの時刻。
.TP 
\fImsg_ctime\fP
Time of creation of queue or time of last \fBmsgctl\fP()  \fBIPC_SET\fP operation.
.TP 
\fImsg_cbytes\fP
Number of bytes in all messages currently on the message queue.  This is a
nonstandard Linux extension that is not specified in POSIX.
.TP 
\fImsg_qnum\fP
Number of messages currently on the message queue.
.TP 
\fImsg_qbytes\fP
Maximum number of bytes of message text allowed on the message queue.
.TP 
\fImsg_lspid\fP
最後の \fBmsgsnd\fP(2) システムコールを実行したプロセスの ID。
.TP 
\fImsg_lrpid\fP
最後の \fBmsgrcv\fP(2) システムコールを実行したプロセスの ID。
.PP
\fIipc_perm\fP 構造体は以下のように定義されている (強調されたフィールドは \fBIPC_SET\fP を使って設定可能である):
.PP
.in +4n
.EX
struct ipc_perm {
    key_t          __key;       /* msgget(2) に与えるキー */
    uid_t          \fBuid\fP;         /* 所有者の実効 UID */
    gid_t          \fBgid\fP;         /* 所有者の実効 GID */
    uid_t          cuid;        /* 作成者の実効 UID */
    gid_t          cgid;        /* 作成者の実効 GID */
    unsigned short \fBmode\fP;        /* 許可 */
    unsigned short __seq;       /* シーケンス番号 */
};
.EE
.in
.PP
The least significant 9 bits of the \fImode\fP field of the \fIipc_perm\fP
structure define the access permissions for the message queue.  The
permission bits are as follows:
.TS
l l.
0400	ユーザーによる読み出し
0200	ユーザーによる書き込み
0040	グループによる読み出し
0020	グループによる書き込み
0004	他人 (others) による読み出し
0002	他人 (others) による書き込み
.TE
.PP
ビット 0100, 0010, 0001 (実行ビット) をシステムは使用しない。
.PP
\fIcmd\fP として有効な値は:
.TP 
\fBIPC_STAT\fP
\fImsqid\fP に関連づけられたメッセージキューデータ構造体から、ポインター \fIbuf\fP が指し示す \fImsqid_ds\fP
構造体に情報をコピーする。 呼び出し側はメッセージキューに対する読み込み許可を持っていなければならない。
.TP 
\fBIPC_SET\fP
Write the values of some members of the \fImsqid_ds\fP structure pointed to by
\fIbuf\fP to the kernel data structure associated with this message queue,
updating also its \fImsg_ctime\fP member.
.IP
The following members of the structure are updated: \fImsg_qbytes\fP,
\fImsg_perm.uid\fP, \fImsg_perm.gid\fP, and (the least significant 9 bits of)
\fImsg_perm.mode\fP.
.IP
The effective UID of the calling process must match the owner
(\fImsg_perm.uid\fP)  or creator (\fImsg_perm.cuid\fP)  of the message queue, or
the caller must be privileged.  Appropriate privilege (Linux: the
\fBCAP_SYS_RESOURCE\fP capability) is required to raise the \fImsg_qbytes\fP value
beyond the system parameter \fBMSGMNB\fP.
.TP 
\fBIPC_RMID\fP
メッセージキューをただちに削除する。 同時にその構造体の読み書きの待ち状態にあったプロセスに通知する (エラーが返り、 \fIerrno\fP が
\fBEIDRM\fP に設定される)。 呼び出したプロセスが適切な特権を持っているか、 呼び出したプロセスの実効ユーザー ID がメッセージキューの作成者か
所有者の実効ユーザー ID でなければならない。この場合、 \fBmsgctl\fP() の第 3 引数は無視される。
.TP 
\fBIPC_INFO\fP (Linux 固有)
システム全体でのメッセージキューの制限とパラメーターに関する情報を、 \fIbuf\fP が指す構造体に入れて返す。 この構造体は \fImsginfo\fP
型である (そのためキャストが必要である)。 \fImsginfo\fP は \fB_GNU_SOURCE\fP 機能検査マクロが定義された場合に
\fI<sys/msg.h>\fP で以下のように定義される:
.IP
.in +4n
.EX
struct msginfo {
    int msgpool; /* メッセージデータの保持に使用される
                    バッファープールの大きさ (1024 バイト単位);
                    カーネル内では未使用 */
    int msgmap;  /* メッセージマップの最大エントリー数;
                    カーネル内では未使用 */
    int msgmax;  /* 一つのメッセージに書き込み可能な
                    最大バイト数 */
    int msgmnb;  /* 一つのキューに書き込み可能な最大バイト数;
                    (msgget(2) での) キュー作成中の msg_qbytes
                    の初期化に使用される */
    int msgmni;  /* メッセージキューの数の最大値 */
    int msgssz;  /* メッセージセグメントのサイズ;
                    カーネル内では未使用 */
    int msgtql;  /* システム上の全キューの最大メッセージ数;
                    カーネル内では未使用 */
    unsigned short msgseg;
                 /* 最大セグメント数; カーネル内では未使用 */
};
.EE
.in
.IP
設定 \fImsgmni ,\fP \fImsgmax ,\fP \fImsgmnb\fP は \fI/proc\fP にある同じ名前のファイル経由で変更可能である。 詳しくは
\fBproc\fP(5)  を参照。
.TP 
\fBMSG_INFO\fP (Linux 固有)
\fBIPC_INFO\fP のときと同じ情報を格納した \fImsginfo\fP 構造体を返す。 但し、以下のフィールドにはメッセージキューが
消費しているシステム資源に関する情報が格納される点が異なる。 \fImsgpool\fP フィールドは現在システム上に存在するメッセージキューの数を返す。
\fImsgmap\fP フィールドはシステム上の全てのキューに入っているメッセージ総数を返す。 \fImsgtql\fP
フィールドはシステム上の全てのキューに入っている全メッセージの 総バイト数を返す。
.TP 
\fBMSG_STAT\fP (Linux 固有)
\fBIPC_STAT\fP と同じく \fImsqid_ds\fP 構造体を返す。 但し、 \fImsqid\fP
引数は、キュー識別子ではなく、システム上の全てのメッセージキュー に関する情報を管理するカーネルの内部配列へのインデックスである。
.TP 
\fBMSG_STAT_ANY\fP (Linux 固有, Linux 4.17 以降)
Return a \fImsqid_ds\fP structure as for \fBMSG_STAT\fP.  However,
\fImsg_perm.mode\fP is not checked for read access for \fImsqid\fP meaning that
any user can employ this operation (just as any user may read
\fI/proc/sysvipc/msg\fP to obtain the same information).
.SH 返り値
On success, \fBIPC_STAT\fP, \fBIPC_SET\fP, and \fBIPC_RMID\fP return 0.  A successful
\fBIPC_INFO\fP or \fBMSG_INFO\fP 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 \fBMSG_STAT\fP or
\fBMSG_STAT_ANY\fP operations to obtain information about all queues on the
system.)  A successful \fBMSG_STAT\fP or \fBMSG_STAT_ANY\fP operation returns the
identifier of the queue whose index was given in \fImsqid\fP.
.PP
エラーの場合は \-1 を返し、 \fIerrno\fP を適切に設定する。
.SH エラー
失敗した場合、 \fIerrno\fP は以下の値の中のどれか一つに設定される:
.TP 
\fBEACCES\fP
The argument \fIcmd\fP is equal to \fBIPC_STAT\fP or \fBMSG_STAT\fP, but the calling
process does not have read permission on the message queue \fImsqid\fP, and
does not have the \fBCAP_IPC_OWNER\fP capability in the user namespace that
governs its IPC namespace.
.TP 
\fBEFAULT\fP
引数 \fIcmd\fP が \fBIPC_SET\fP か \fBIPC_STAT\fP で、ポインター \fIbuf\fP で指されているアドレスがアクセス可能でない。
.TP 
\fBEIDRM\fP
メッセージキューが削除された。
.TP 
\fBEINVAL\fP
\fIcmd\fP または \fImsqid\fP に不正な値が設定された。 もしくは、 \fBMSG_STAT\fP 操作の場合に、 \fImsqid\fP
で指定されたインデックス値が現在未使用の配列のスロットを参照いていた。
.TP 
\fBEPERM\fP
引数 \fIcmd\fP が \fBIPC_SET\fP か \fBIPC_RMID\fP であるが、呼び出したプロセスの実効ユーザー ID がメッセージキューの
(\fImsg_perm.cuid\fP として見つかる) 作成者 と (\fImsg_perm.uid\fP として見つかる) 所有者のいずれでもなく、
かつ呼び出し者に特権がない (Linux では \fBCAP_SYS_ADMIN\fP ケーパビリティがない)。
.TP 
\fBEPERM\fP
\fBIPC_SET\fP で \fImsg_qbytes\fP をシステムパラメーター \fBMSGMNB\fP
より大きな値に設定しようとしたが、呼び出し元が特権を持っていなかった (Linux では、 \fBCAP_SYS_RESOURCE\fP
ケーパビリティを持っていなかった)。
.SH 準拠
.\" SVID does not document the EIDRM error condition.
POSIX.1\-2001, POSIX.1\-2008, SVr4.
.SH 注意
.\" Like Linux, the FreeBSD man pages still document
.\" the inclusion of these header files.
Linux や POSIX の全てのバージョンでは、 \fI<sys/types.h>\fP と \fI<sys/ipc.h>\fP
のインクルードは必要ない。しかしながら、いくつかの古い実装ではこれらのヘッダーファイルのインクルードが必要であり、 SVID
でもこれらのインクルードをするように記載されている。このような古いシステムへの移植性を意図したアプリケーションではこれらのファイルをインクルードする必要があるかもしれない。
.PP
\fBIPC_INFO\fP, \fBMSG_STAT\fP, \fBMSG_INFO\fP 操作は、 \fBipcs\fP(1)
プログラムで割り当て済の資源に関する情報を提供するために 使用されている。将来、これらの操作は変更されたり、 \fI/proc\fP
ファイルシステムのインターフェースに移動されるかもしれない。
.PP
\fIstruct msqid_ds\fP 内の多くのフィールドは、 Linux 2.2 では \fIshort\fP だったが、Linux 2.4 では
\fIlong\fP になった。 この利点を生かすには、glibc\-2.1.91 以降の環境下で 再コンパイルすれば十分である。
(カーネルは新しい形式の呼び出しと古い形式の呼び出しを \fIcmd\fP 内の \fBIPC_64\fP フラグで区別する。)
.SH 関連項目
\fBmsgget\fP(2), \fBmsgrcv\fP(2), \fBmsgsnd\fP(2), \fBcapabilities\fP(7),
\fBmq_overview\fP(7), \fBsysvipc\fP(7)
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は
\%https://www.kernel.org/doc/man\-pages/ に書かれている。