release/man2/msgop.2

   1 .\" Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" Modified Tue Oct 22 16:40:11 1996 by Eric S. Raymond <esr@thyrsus.com>
  26 .\" Modified Mon Jul 10 21:09:59 2000 by aeb
  27 .\" Modified 1 Jun 2002, Michael Kerrisk <mtk.manpages@gmail.com>
  28 .\"     Language clean-ups.
  29 .\"     Enhanced and corrected information on msg_qbytes, MSGMNB and MSGMAX
  30 .\"     Added note on restart behavior of msgsnd() and msgrcv()
  31 .\"     Formatting clean-ups (argument and field names marked as .I
  32 .\"             instead of .B)
  33 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  34 .\"     Added notes on capability requirements
  35 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  36 .\"     Language and formatting clean-ups
  37 .\"     Added notes on /proc files
  38 .\"
  39 .\" FIXME Add example programs to this page.
  40 .\"
  41 .\"*******************************************************************
  42 .\"
  43 .\" This file was generated with po4a. Translate the source file.
  44 .\"
  45 .\"*******************************************************************
  46 .\"
  47 .\" Japanese Version Copyright (c) 1997 HANATAKA Shinya
  48 .\"         all rights reserved.
  49 .\" Translated 1997-02-23, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  50 .\" Modified 2000-09-23, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  51 .\" Updated 2002-11-26, Kentaro Shirakata <argrath@ub32.org>
  52 .\" Updated 2005-03-04, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  53 .\" Updated 2006-03-05, Akihiro MOTOKI, LDP v2.25
  54 .\" Updated 2008-08-09, Akihiro MOTOKI, LDP v3.05
  55 .\" Updated 2013-05-01, Akihiro MOTOKI <amotoki@gmail.com>
  56 .\"
  57 .TH MSGOP 2 2014\-08\-19 Linux "Linux Programmer's Manual"
  58 .SH 名前
  59 msgrcv, msgsnd \- System V メッセージキュー操作
  60 .SH 書式
  61 .nf
  62 \fB#include <sys/types.h>\fP
  63 \fB#include <sys/ipc.h>\fP
  64 \fB#include <sys/msg.h>\fP
  65 .sp
  66 \fBint msgsnd(int \fP\fImsqid\fP\fB, const void *\fP\fImsgp\fP\fB, size_t \fP\fImsgsz\fP\fB, int \fP\fImsgflg\fP\fB);\fP
  67 .sp
  68 \fBssize_t msgrcv(int \fP\fImsqid\fP\fB, void *\fP\fImsgp\fP\fB, size_t \fP\fImsgsz\fP\fB, long \fP\fImsgtyp\fP\fB,\fP
  69 \fB               int \fP\fImsgflg\fP\fB);\fP
  70 .fi
  71 .SH 説明
  72 システムコール \fBmsgsnd\fP()  と \fBmsgrcv\fP()  はそれぞれ、 System\ V メッセージキューへのメッセージの送信と、
  73 メッセージの受信に使用される。呼び出し元プロセスは、 メッセージを送信するためにはメッセージキューに対する書き込み許可を、
  74 メッセージを受信するためには読み出し許可を持っていなければならない。
  75 .PP
  76 呼び出し元プロセスは以下に示す構造体を用意し、この構造体への ポインターを \fImsgp\fP 引き数として渡す。
  77 .in +4n
  78 .nf
  79
  80 struct msgbuf {
  81     long mtype;       /* message type, must be > 0 */
  82     char mtext[1];    /* message data */
  83 };
  84 .fi
  85 .in
  86 .PP
  87 \fImtext\fP フィールドは配列 (または他の構造体) で、その大きさは 非負の整数である \fImsgsz\fP で指定される。 長さ 0 のメッセージ
  88 (つまり \fImtext\fP フィールドがないメッセージ) も認められている。 \fBmtype\fP フィールドは厳密に正の整数でなければならない。
  89 この値は、メッセージを受信するプロセスでメッセージを選択するために 使用される (下記の \fBmsgrcv\fP()  の説明を参照のこと)。
  90 .SS msgsnd()
  91 \fBmsgsnd\fP()  システムコールは \fImsgp\fP 引き数で指定されたメッセージのコピーを \fImsqid\fP
  92 で指定された識別子を持つメッセージキューへ追加する。
  93 .PP
  94 キューに十分な空き容量がある場合、 \fBmsgsnd\fP()  は直ちに成功する。 キューの容量は、メッセージキューのデータ構造体の
  95 \fImsg_qbytes\fP フィールドで制御される。 キュー作成時にこのフィールドは \fBMSGMNB\fP に初期化されるが、この制限は
  96 \fBmsgctl\fP(2)  を使って変更できる。 次のいずれかの条件が成立する場合に、メッセージキューは一杯と判断される。
  97 .IP * 2
  98 新しいメッセージをそのキューに追加すると、 そのキューの全バイト数がキューの最大サイズ (\fImsg_qbytes\fP フィールド)
  99 を超過してしまう場合。
 100 .IP *
 101 そのキューにもう一つメッセージを追加すると、 そのキューが全メッセージ数がキューの最大サイズ (\fImsg_qbytes\fP フィールド)
 102 を超過してしまう場合。 このチェックは、無限個の長さ 0 のメッセージをそのキューに追加するのを防ぐために必要である。 長さ 0
 103 のメッセージはデータを含まないが、 (ロックされた) カーネルメモリーを消費するからである。
 104 .PP
 105 そのキューに十分な領域がない場合、 デフォルトの動作では、 必要な領域ができるまで \fBmsgsnd\fP() は停止 (block) する。
 106 \fImsgflg\fP に \fBIPC_NOWAIT\fP が指定された場合、 \fBmsgsnd\fP() はエラー \fBEAGAIN\fP で失敗する。
 107
 108 停止している \fBmsgsnd\fP()  は以下の場合にも失敗する。
 109 .IP * 2
 110 キューが削除された。 この場合、 \fIerrno\fP は \fBEIDRM\fP に設定される。
 111 .IP *
 112 シグナルが捕捉された。 この場合、 \fIerrno\fP は \fBEINTR\fP に設定される。 \fBsignal\fP(7)  参照。 (\fBmsgsnd\fP()
 113 は、たとえシグナルハンドラーの設定時に \fBSA_RESTART\fP を指定していたとしても、シグナルハンドラーによって割り込まれた後で
 114 自動的に再スタートすることは決してない。)
 115 .PP
 116 正常に終了した場合、メッセージキューのデータ構造体は以下のように 更新される:
 117 .IP
 118 \fImsg_lspid\fP には呼び出し元プロセスのプロセス ID が設定される。
 119 .IP
 120 \fImsg_qnum\fP は 1 増加する。
 121 .IP
 122 \fImsg_stime\fP には現在時刻が設定される。
 123 .SS msgrcv()
 124 \fBmsgrcv\fP()  システムコールは \fImsqid\fP で指定されたキューからメッセージを削除し、 \fImsgp\fP
 125 で指定されたバッファーにそのメッセージを格納する。
 126 .PP
 127 \fImsgsz\fP 引き数には \fImsgp\fP 引き数で指定された構造体の \fImtext\fP メンバーの最大のバイト数を指定する。
 128 メッセージのテキストの長さが \fImsgsz\fP より大きい場合の動作は、 \fImsgflg\fP に \fBMSG_NOERROR\fP
 129 が指定されているかどうかで決まる。 \fBMSG_NOERROR\fP が指定されていれば、メッセージのテキストは切り詰められる
 130 (切り捨てられた部分は失われる)。 \fBMSG_NOERROR\fP が指定されていなければ、メッセージはキューから削除されず、 システムコールは \-1
 131 を返して失敗し、 \fIerrno\fP に \fBE2BIG\fP が設定される。
 132 .PP
 133 \fBMSG_COPY\fP が \fImsgflg\fP に指定されていない場合 (下記参照)、 \fImsgtyp\fP 引き数には要求するメッセージの型を指定する。
 134 型は以下のように指定する:
 135 .IP * 2
 136 \fImsgtyp\fP が 0 ならば、キューの最初にあるメッセージが読み込まれる。
 137 .IP *
 138 \fImsgtyp\fP が 0 より大きい場合、 \fImsgflg\fP に \fBMSG_EXCEPT\fP が指定されていなければ、 \fImsgtyp\fP
 139 型のキューの最初のメッセージが読み込まれる。 \fBMSG_EXCEPT\fP が指定された場合は、 \fImsgtyp\fP
 140 型以外のキューの最初のメッセージが読み込まれる。
 141 .IP *
 142 \fImsgtyp\fP が 0 より小さければ、 \fImsgtyp\fP の絶対値以下で最も小さい型を持つキューの最初のメッセージが読み込まれる。
 143 .PP
 144 \fImsgflg\fP 引き数には、以下のフラグを任意の数だけ (0個も可)、これらの OR で指定する:
 145 .TP
 146 \fBIPC_NOWAIT\fP
 147 キューに要求された型のメッセージがない場合には直ちに返る。 システムコールは失敗し、 \fIerrno\fP には \fBENOMSG\fP が設定される。
 148 .TP
 149 \fBMSG_COPY\fP (Linux 3.8 以降)
 150 .\" commit 4a674f34ba04a002244edaf891b5da7fc1473ae8
 151 キューの中で \fImsgtyp\fP で指定した位置にあるメッセージのコピーを、キューを変更せずに (非破壊的に) 取り出す (メッセージの位置は 0
 152 から順番に番号が割り当てられる)。
 153
 154 このフラグは \fBIPC_NOWAIT\fP と組み合わせて指定しなければならない。 その結果、指定した位置にメッセージがなかった場合、呼び出しはエラー
 155 \fBENOMSG\fP ですぐに失敗する。 \fBMSG_COPY\fP と \fBMSG_EXCEPT\fP は \fImsgtyp\fP
 156 の意味を相容れない方法で使用するため、この二つのフラグの両方を \fImsgtyp\fP に指定することはできない。
 157
 158 \fBMSG_COPY\fP フラグは、 カーネルのチェックポイント復元 (checkpoint\-restore) 機能の実装のために追加された。
 159 このフラグはカーネルが \fBCONFIG_CHECKPOINT_RESTORE\fP オプションを有効にして作成された場合にのみ利用できる。
 160 .TP
 161 \fBMSG_EXCEPT\fP
 162 0 より大きな \fImsgtyp\fP と一緒に使用して、 \fImsgtyp\fP 以外のキューの最初のメッセージを読み込む。
 163 .TP
 164 \fBMSG_NOERROR\fP
 165 \fImsgsz\fP バイトよりも長かった場合はメッセージのテキストを切り詰める。
 166 .PP
 167 要求された型のメッセージが存在せず、 \fImsgflg\fP に \fBIPC_NOWAIT\fP が指定されていなかった場合、呼び出し元プロセスは
 168 以下のいずれかの状況になるまで停止 (block) される:
 169 .IP * 2
 170 要求している型のメッセージがキューへ入れられた。
 171 .IP *
 172 メッセージキューがシステムから削除された。 この場合、システムコールは失敗し、 \fIerrno\fP に \fBEIDRM\fP が設定される。
 173 .IP *
 174 呼び出し元プロセスがシグナルを捕獲した。 この場合、システムコールは失敗し、 \fIerrno\fP に \fBEINTR\fP が設定される。
 175 (\fBmsgrcv\fP()  は、たとえシグナルハンドラーの設定時に \fBSA_RESTART\fP
 176 を指定していたとしても、シグナルハンドラーによって割り込まれた後で 自動的に再スタートすることは決してない。)
 177 .PP
 178 正常に終了した場合、メッセージキューのデータ構造体は以下のように 更新される:
 179 .IP
 180 \fImsg_lrpid\fP には呼び出し元プロセスのプロセス ID が設定される。
 181 .IP
 182 \fImsg_qnum\fP は 1 減算される。
 183 .IP
 184 \fImsg_rtime\fP には現在の時刻が設定される。
 185 .SH 返り値
 186 失敗した場合は、どちらの関数も \-1 を返し、エラーを \fIerrno\fP に表示する。成功した場合、 \fBmsgsnd\fP()  は 0 を返し、
 187 \fBmsgrcv\fP()  は \fImtext\fP 配列に実際にコピーしたバイト数を返す。
 188 .SH エラー
 189 \fBmsgsnd\fP()  が失敗した場合、 \fBerrno\fP に以下の値のいずれかが設定される:
 190 .TP
 191 \fBEACCES\fP
 192 呼び出し元プロセスにはメッセージキューに対する書き込み許可がなく、 \fBCAP_IPC_OWNER\fP ケーパビリティもない。
 193 .TP
 194 \fBEAGAIN\fP
 195 \fImsg_qbytes\fP がキューの制限を超えていたため、メッセージを送ることができず、かつ \fImsgflg\fP に \fBIPC_NOWAIT\fP
 196 が指定されていた。
 197 .TP
 198 \fBEFAULT\fP
 199 \fImsgp\fP が指しているアドレスがアクセス可能でない。
 200 .TP
 201 \fBEIDRM\fP
 202 メッセージキューが削除された。
 203 .TP
 204 \fBEINTR\fP
 205 メッセージキューが要求した条件を満たすまで停止している時に、 プロセスがシグナルを捕獲した。
 206 .TP
 207 \fBEINVAL\fP
 208 \fImsqid\fP が不適切な値であるか、 \fImtype\fP が正の値でないか、 \fImsgsz\fP が不適切な値 (0 以下か、システムで決まる値
 209 \fBMSGMAX\fP よりも大きい値) である。
 210 .TP
 211 \fBENOMEM\fP
 212 \fImsgp\fP が指すメッセージのコピーを作成するのに十分なメモリーがシステムに存在しない。
 213 .PP
 214 \fBmsgrcv\fP()  が失敗した場合には \fIerrno\fP に以下の値のいずれかが設定される:
 215 .TP
 216 \fBE2BIG\fP
 217 メッセージのテキストの長さが \fImsgsz\fP よりも大きく、 \fImsgflg\fP に \fBMSG_NOERROR\fP が設定されていなかった。
 218 .TP
 219 \fBEACCES\fP
 220 呼び出し元プロセスにはメッセージキューに対する読み込み許可がなく、 \fBCAP_IPC_OWNER\fP ケーパビリティもない。
 221 .TP
 222 \fBEAGAIN\fP
 223 キューにはメッセージがなく、 \fImsgflg\fP に \fBIPC_NOWAIT\fP が指定された。
 224 .TP
 225 \fBEFAULT\fP
 226 \fImsgp\fP が指しているアドレスがアクセス可能でない。
 227 .TP
 228 \fBEIDRM\fP
 229 メッセージを受信するためにプロセスが停止している間に、 メッセージキューが削除された。
 230 .TP
 231 \fBEINTR\fP
 232 メッセージを受けるためにプロセスが停止している間に、 プロセスがシグナルを捕獲した。 \fBsignal\fP(7)  参照。
 233 .TP
 234 \fBEINVAL\fP
 235 \fImsgqid\fP が不正か、 \fImsgsz\fP が 0 より小さい。
 236 .TP
 237 \fBEINVAL\fP (Linux 3.14 以降)
 238 \fImsgflg\fP に \fBMSG_COPY\fP が指定されたが、 \fBIPC_NOWAIT\fP が指定されていない。
 239 .TP
 240 \fBEINVAL\fP (Linux 3.14 以降)
 241 \fImsgflg\fP に \fBMSG_COPY\fP と \fBMSG_EXCEPT\fP の両方が指定された。
 242 .TP
 243 \fBENOMSG\fP
 244 \fImsgflg\fP に \fBIPC_NOWAIT\fP が設定されており、 メッセージキューに要求された型のメッセージが存在しなかった。
 245 .TP
 246 \fBENOMSG\fP
 247 \fBIPC_NOWAIT\fP と \fBMSG_COPY\fP が \fImsgflg\fP に指定されたが、 キューには \fImsgtyp\fP
 248 未満のメッセージしか入っていなかった。
 249 .TP
 250 \fBENOSYS\fP (Linux 3.8 以降)
 251 \fImsgflg\fP に \fIMSG_COPY\fP が指定されたが、カーネルが \fBCONFIG_CHECKPOINT_RESTORE\fP
 252 なしで作成されている。
 253 .SH 準拠
 254 SVr4, POSIX.1\-2001.
 255
 256 .\" MSG_COPY since glibc 2.18
 257 フラグ \fBMSG_EXCEPT\fP と \fBMSG_COPY\fP は Linux 固有である。 これらの定義を得るには、機能検査マクロ
 258 \fB_GNU_SOURCE\fP を定義する。
 259 .SH 注意
 260 .\" Like Linux, the FreeBSD man pages still document
 261 .\" the inclusion of these header files.
 262 Linux や POSIX の全てのバージョンでは、 \fI<sys/types.h>\fP と \fI<sys/ipc.h>\fP
 263 のインクルードは必要ない。しかしながら、いくつかの古い実装ではこれらのヘッダーファイルのインクルードが必要であり、 SVID
 264 でもこれらのインクルードをするように記載されている。このような古いシステムへの移植性を意図したアプリケーションではこれらのファイルをインクルードする必要があるかもしれない。
 265
 266 \fImsgp\fP 引き数は、 glibc 2.0 と 2.1 では \fIstruct msgbuf\ *\fP と宣言されている。glibc 2.2
 267 以降では、 SUSv2 と SUSv3 の要求通り、\fIvoid\ *\fP と宣言されている。
 268
 269 以下は \fBmsgsnd\fP システムコールに影響するシステム制限である:
 270 .TP
 271 \fBMSGMAX\fP
 272 メッセージのテキストの最大サイズ: 8192 バイト (Linux では、この制限値は \fI/proc/sys/kernel/msgmax\fP
 273 経由で読み出したり変更したりできる)。
 274 .TP
 275 \fBMSGMNB\fP
 276 バイト単位でのメッセージキューのデフォルトの最大サイズ : 16384 バイト。 (Linux では、この制限値は
 277 \fI/proc/sys/kernel/msgmnb\fP 経由で読み出したり変更したりできる)。 特権プロセス (Linux ではケーパビリティ
 278 \fBCAP_SYS_RESOURCE\fP を持ったプロセス) は \fBmsgctl\fP(2)  システムコールでメッセージキューのサイズを
 279 \fBMSGMNB\fP よりも大きい値に増やすことができる。
 280 .PP
 281 現在の実装では、システム全体のメッセージヘッダーの上限数 (\fBMSGTQL\fP)  と、システム全体のメッセージプールの最大バイト数
 282 (\fBMSGPOOL\fP)  に関して実装依存の制限はない。
 283 .SH バグ
 284 .\" http://marc.info/?l=linux-kernel&m=139048542803605&w=2
 285 .\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c
 286 Linux 3.13 以前では、 \fBmsgrcv\fP() の呼び出しで \fBMSG_COPY\fP フラグは指定されたが \fBIPC_NOWAIT\fP
 287 は指定されず、かつメッセージキューに \fImsgtyp\fP 未満のメッセージしかない場合に、 \fBmsgrcv\fP()
 288 の呼び出しはキューに次のメッセージが書き込まれるまで停止していた。 新しいメッセージが書き込まれた時点で、 そのメッセージが指定された位置
 289 \fImsgtyp\fP かどうかに\fI関わらず\fP、 \fBmsgrcv\fP() の呼び出しは新たに書き込まれたメッセージのコピーを返していた。 このバグは
 290 Linux ３．１４で修正された。
 291
 292 .\" http://marc.info/?l=linux-kernel&m=139048542803605&w=2
 293 .\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c
 294 \fImsg_copy\fP に \fBMSG_COPY\fP と \fBMSG_EXCEPT\fP の両方を指定するのは、論理的なエラーである
 295 (なぜならこれらのフラグは \fImsgtyp\fP を別の意味で解釈するからである)。 Linux 3.13 以前では、\fBmsgrcv\fP()
 296 がこのエラーを検出しなかった。 このバグは Linux 3.14 で修正された。
 297 .SH 関連項目
 298 \fBmsgctl\fP(2), \fBmsgget\fP(2), \fBcapabilities\fP(7), \fBmq_overview\fP(7),
 299 \fBsvipc\fP(7)
 300 .SH この文書について
 301 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
 302 である。プロジェクトの説明とバグ報告に関する情報は
 303 http://www.kernel.org/doc/man\-pages/ に書かれている。