release/man2/msgctl.2

   1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
   2 .\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
  27 .\" Modified Sun Feb 18 01:59:29 2001 by Andries E. Brouwer <aeb@cwi.nl>
  28 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  29 .\"     Added notes on CAP_IPC_OWNER requirement
  30 .\" Modified, 17 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  31 .\"     Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID
  32 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  33 .\"     Language and formatting clean-ups
  34 .\"     Added msqid_ds and ipc_perm structure definitions
  35 .\" 2005-08-02, mtk: Added IPC_INFO, MSG_INFO, MSG_STAT descriptions
  36 .\"
  37 .\"*******************************************************************
  38 .\"
  39 .\" This file was generated with po4a. Translate the source file.
  40 .\"
  41 .\"*******************************************************************
  42 .TH MSGCTL 2 2012\-05\-31 Linux "Linux Programmer's Manual"
  43 .SH 名前
  44 msgctl \- System V メッセージ制御操作
  45 .SH 書式
  46 .nf
  47 \fB#include <sys/types.h>\fP
  48 \fB#include <sys/ipc.h>\fP
  49 \fB#include <sys/msg.h>\fP
  50
  51 \fBint msgctl(int \fP\fImsqid\fP\fB, int \fP\fIcmd\fP\fB, struct msqid_ds *\fP\fIbuf\fP\fB);\fP
  52 .fi
  53 .SH 説明
  54 \fBmsgctl\fP()  はメッセージ・キュー識別子 \fImsqid\fP で指定された System V メッセージ・キュー (message
  55 queue) に対して \fIcmd\fP で指定された制御操作を行なう。
  56 .PP
  57 \fImsqid_ds\fP データ構造体は \fI<sys/msg.h>\fP で以下のように定義されている:
  58 .nf
  59 .in +4n
  60
  61 struct msqid_ds {
  62     struct ipc_perm msg_perm;     /* 所有権と許可 */
  63     time_t          msg_stime;    /* 最後の msgsnd(2) の時刻 */
  64     time_t          msg_rtime;    /* 最後の msgrcv(2) の時刻 */
  65     time_t          msg_ctime;    /* 最後に変更が行われた時刻 */
  66     unsigned long   __msg_cbytes; /* キューにある現在のバイト数
  67                                      (非標準) */
  68     msgqnum_t       msg_qnum;     /* キューにある現在入っている
  69                                      メッセージの数 */
  70     msglen_t        msg_qbytes;   /* キューに許可されている
  71                                      最大バイト数 */
  72     pid_t           msg_lspid;    /* 最後の msgsnd(2) の PID */
  73     pid_t           msg_lrpid;    /* 最後の msgrcv(2) の PID */
  74 };
  75 .in
  76 .fi
  77 .PP
  78 \fIipc_perm\fP 構造体は以下のように定義されている (強調されたフィールドは \fBIPC_SET\fP を使って設定可能である):
  79 .PP
  80 .nf
  81 .in +4n
  82 struct ipc_perm {
  83     key_t          __key;       /* msgget(2) に与えるキー */
  84     uid_t          \fBuid\fP;         /* 所有者の実効 UID */
  85     gid_t          \fBgid\fP;         /* 所有者の実効 GID */
  86     uid_t          cuid;        /* 作成者の実効 UID */
  87     gid_t          cgid;        /* 作成者の実効 GID */
  88     unsigned short \fBmode\fP;        /* 許可 */
  89     unsigned short __seq;       /* シーケンス番号 */
  90 };
  91 .in
  92 .fi
  93 .PP
  94 \fIcmd\fP として有効な値は:
  95 .TP
  96 \fBIPC_STAT\fP
  97 \fImsqid\fP に関連づけられたメッセージ・キュー・データ構造体から、ポインタ \fIbuf\fP が指し示す \fImsqid_ds\fP
  98 構造体に情報をコピーする。 呼び出し側はメッセージ・キューに対する読み込み許可を持っていなければならない。
  99 .TP
 100 \fBIPC_SET\fP
 101 ポインタ \fIbuf\fP が指し示す \fImsqid_ds\fP 構造体のメンバーの値を、メッセージ・キューに関連づけられた
 102 カーネル・データ構造体に書き込み、 \fImsg_ctime\fP メンバーも更新する。 構造体のメンバーのうち、更新されるものを以下に示す:
 103 \fImsg_qbytes\fP, \fImsg_perm.uid\fP, \fImsg_perm.gid\fP, \fImsg_perm.mode\fP (の下位 9
 104 ビット)。 呼び出したプロセスの実効ユーザ ID が、メッセージ・キューの所有者 (\fImsg_perm.uid\fP)  または作成者
 105 (\fImsg_perm.cuid\fP)  と一致するか、呼び出し元が特権を持たなければならない。 \fImsg_qbytes\fP をシステム・パラメータの
 106 \fBMSGMNB\fP を超えて設定するには、適切な特権 (Linux では \fBCAP_IPC_RESOURCE\fP ケーパビリティ
 107 (capability)) が必要である。
 108 .TP
 109 \fBIPC_RMID\fP
 110 メッセージ・キューをただちに削除する。 同時にその構造体の読み書きの待ち状態にあったプロセスに通知する (エラーが返り、 \fIerrno\fP が
 111 \fBEIDRM\fP に設定される)。 呼び出したプロセスが適切な特権を持っているか、 呼び出したプロセスの実効ユーザ ID がメッセージ・キューの作成者か
 112 所有者の実効ユーザ ID でなければならない。
 113 .TP
 114 \fBIPC_INFO\fP (Linux 固有)
 115 システム全体でのメッセージ・キューの制限とパラメータに関する情報を、 \fIbuf\fP が指す構造体に入れて返す。 この構造体は \fImsginfo\fP
 116 型である (そのためキャストが必要である)。 \fImsginfo\fP は \fB_GNU_SOURCE\fP 機能検査マクロが定義された場合に
 117 \fI<sys/msg.h>\fP で以下のように定義される:
 118 .nf
 119 .in +4n
 120
 121 struct msginfo {
 122     int msgpool; /* メッセージ・データの保持に使用される
 123                     バッファ・プールの大きさ (1024 バイト単位);
 124                     カーネル内では未使用 */
 125     int msgmap;  /* メッセージ・マップの最大エントリ数;
 126                     カーネル内では未使用 */
 127     int msgmax;  /* 一つのメッセージに書き込み可能な
 128                     最大バイト数 */
 129     int msgmnb;  /* 一つのキューに書き込み可能な最大バイト数;
 130                     (msgget(2) での) キュー作成中の msg_qbytes
 131                     の初期化に使用される */
 132     int msgmni;  /* メッセージ・キューの数の最大値 */
 133     int msgssz;  /* メッセージ・セグメントのサイズ;
 134                     カーネル内では未使用 */
 135     int msgtql;  /* システム上の全キューの最大メッセージ数;
 136                     カーネル内では未使用 */
 137     unsigned short int msgseg;
 138                  /* 最大セグメント数; カーネル内では未使用 */
 139 };
 140
 141 .in
 142 .fi
 143 設定 \fImsgmni ,\fP \fImsgmax ,\fP \fImsgmnb\fP は \fI/proc\fP にある同じ名前のファイル経由で変更可能である。 詳しくは
 144 \fBproc\fP(5)  を参照。
 145 .TP
 146 \fBMSG_INFO\fP (Linux 固有)
 147 \fBIPC_INFO\fP のときと同じ情報を格納した \fImsginfo\fP 構造体を返す。 但し、以下のフィールドにはメッセージ・キューが
 148 消費しているシステム資源に関する情報が格納される点が異なる。 \fImsgpool\fP フィールドは現在システム上に存在するメッセージ・キューの数を返す。
 149 \fImsgmap\fP フィールドはシステム上の全てのキューに入っているメッセージ総数を返す。 \fImsgtql\fP
 150 フィールドはシステム上の全てのキューに入っている全メッセージの 総バイト数を返す。
 151 .TP
 152 \fBMSG_STAT\fP (Linux 固有)
 153 \fBIPC_STAT\fP と同じく \fImsqid_ds\fP 構造体を返す。 但し、 \fImsqid\fP
 154 引き数は、キュー識別子ではなく、システム上の全てのメッセージ・キュー に関する情報を管理するカーネルの内部配列へのインデックスである。
 155 .SH 返り値
 156 成功すると、 \fBIPC_STAT\fP, \fBIPC_SET\fP, \fBIPC_RMID\fP は 0 を返す。 \fBIPC_INFO\fP と
 157 \fBMSG_INFO\fP 操作は、成功すると、全てのメッセージ・キューに関する情報を 管理しているカーネルの内部配列の使用中エントリのインデックスの
 158 うち最大値を返す (この情報は、システムの全てのメッセージ・キューに関する情報を 取得するために、 \fBMSG_STAT\fP
 159 操作を繰り返し実行する際に使用できる)。 \fBMSG_STAT\fP 操作は、成功すると、 \fImsqid\fP
 160 で指定されたインデックスを持つメッセージ・キューの識別子を返す。
 161
 162 エラーの場合は \-1 を返し、 \fIerrno\fP を適切に設定する。
 163 .SH エラー
 164 失敗した場合、 \fIerrno\fP は以下の値の中のどれか一つに設定される:
 165 .TP
 166 \fBEACCES\fP
 167 引き数 \fIcmd\fP が \fBIPC_STAT\fP または \fBMSG_STAT\fP に等しいが、呼び出したプロセスがメッセージ・キュー \fImsqid\fP
 168 に対する読み込み許可を持っておらず、かつ \fBCAP_IPC_OWNER\fP ケーパビリティを持っていない。
 169 .TP
 170 \fBEFAULT\fP
 171 引き数 \fIcmd\fP が \fBIPC_SET\fP か \fBIPC_STAT\fP で、ポインタ \fIbuf\fP で指されているアドレスがアクセス可能でない。
 172 .TP
 173 \fBEIDRM\fP
 174 メッセージ・キューが削除された。
 175 .TP
 176 \fBEINVAL\fP
 177 \fIcmd\fP または \fImsqid\fP に不正な値が設定された。 もしくは、 \fBMSG_STAT\fP 操作の場合に、 \fImsqid\fP
 178 で指定されたインデックス値が現在未使用の配列のスロットを参照いていた。
 179 .TP
 180 \fBEPERM\fP
 181 引き数 \fIcmd\fP が \fBIPC_SET\fP か \fBIPC_RMID\fP であるが、呼び出したプロセスの実効ユーザ ID がメッセージキューの
 182 (\fImsg_perm.cuid\fP として見つかる) 作成者 と (\fImsg_perm.uid\fP として見つかる) 所有者のいずれでもなく、
 183 かつ呼び出したプロセスに特権 (Linux では \fBCAP_SYS_ADMIN\fP ケーパビリティ) がない。
 184 .SH 準拠
 185 .\" SVID does not document the EIDRM error condition.
 186 SVr4, POSIX.1\-2001.
 187 .SH 注意
 188 .\" Like Linux, the FreeBSD man pages still document
 189 .\" the inclusion of these header files.
 190 Linux や POSIX の全てのバージョンでは、 \fI<sys/types.h>\fP と \fI<sys/ipc.h>\fP
 191 のインクルードは必要ない。しかしながら、いくつかの古い実装ではこれらのヘッダファイルのインクルードが必要であり、 SVID
 192 でもこれらのインクルードをするように記載されている。このような古いシステムへの移植性を意図したアプリケーションではこれらのファイルをインクルードする必要があるかもしれない。
 193
 194 \fBIPC_INFO\fP, \fBMSG_STAT\fP, \fBMSG_INFO\fP 操作は、 \fBipcs\fP(1)
 195 プログラムで割り当て済の資源に関する情報を提供するために 使用されている。将来、これらの操作は変更されたり、 /proc
 196 ファイルシステムのインタフェースに移動されるかもしれない。
 197
 198 \fIstruct msqid_ds\fP 内の多くのフィールドは、 Linux 2.2 では \fIshort\fP だったが、Linux 2.4 では
 199 \fIlong\fP になった。 この利点を生かすには、glibc\-2.1.91 以降の環境下で 再コンパイルすれば十分である。
 200 (カーネルは新しい形式の呼び出しと古い形式の呼び出しを \fIcmd\fP 内の \fBIPC_64\fP フラグで区別する。)
 201 .SH 関連項目
 202 \fBmsgget\fP(2), \fBmsgrcv\fP(2), \fBmsgsnd\fP(2), \fBcapabilities\fP(7),
 203 \fBmq_overview\fP(7), \fBsvipc\fP(7)
 204 .SH この文書について
 205 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.51 の一部
 206 である。プロジェクトの説明とバグ報告に関する情報は
 207 http://www.kernel.org/doc/man\-pages/ に書かれている。