OSDN Git Service

5cb6b8abe44bb556cda1bcffe389f43ac750c4df
[linuxjm/LDP_man-pages.git] / draft / man2 / msgctl.2
1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
2 .\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\"
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 .\"
24 .\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
25 .\" Modified Sun Feb 18 01:59:29 2001 by Andries E. Brouwer <aeb@cwi.nl>
26 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
27 .\"     Added notes on CAP_IPC_OWNER requirement
28 .\" Modified, 17 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com>
29 .\"     Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID
30 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
31 .\"     Language and formatting clean-ups
32 .\"     Added msqid_ds and ipc_perm structure definitions
33 .\" 2005-08-02, mtk: Added IPC_INFO, MSG_INFO, MSG_STAT descriptions
34 .\"
35 .\" Japanese Version Copyright (c) 1997 HANATAKA Shinya
36 .\"         all rights reserved.
37 .\" Translated 1997-02-23, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
38 .\" Updated & Modified 2001-06-04, Yuichi SATO <ysato@h4.dion.ne.jp>
39 .\" Updated & Modified 2002-07-06, Yuichi SATO
40 .\" Updated & Modified 2004-12-31, Yuichi SATO <ysato444@yahoo.co.jp>
41 .\" Updated & Modified 2005-10-10, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
42 .\"
43 .\"WORD:        message                 メッセージ
44 .\"WORD:        queue                   キュー
45 .\"WORD:        member                  メンバー
46 .\"WORD:        structure               構造体
47 .\"WORD:        effective user ID       実効ユーザ ID
48 .\"WORD:        creator                 作成者
49 .\"WORD:        owner                   所有者
50 .\"WORD:        feature test macro      機能検査マクロ
51 .\"
52 .TH MSGCTL 2 2008-08-06 "Linux" "Linux Programmer's Manual"
53 .\"O .SH NAME
54 .SH 名前
55 .\"O msgctl \- message control operations
56 msgctl \- メッセージ制御操作
57 .\"O .SH SYNOPSIS
58 .SH 書式
59 .nf
60 .B #include <sys/types.h>
61 .B #include <sys/ipc.h>
62 .B #include <sys/msg.h>
63
64 .BI "int msgctl(int " msqid ", int " cmd ", struct msqid_ds *" buf );
65 .fi
66 .\"O .SH DESCRIPTION
67 .SH 説明
68 .\"O .BR msgctl ()
69 .\"O performs the control operation specified by
70 .\"O .I cmd
71 .\"O on the message queue with identifier
72 .\"O .IR msqid .
73 .BR msgctl ()
74 はメッセージ・キュー識別子
75 .I msqid
76 で指定されたメッセージ・キュー (message queue) に対して
77 .I cmd
78 で指定された制御操作を行なう。
79 .PP
80 .\"O The
81 .\"O .I msqid_ds
82 .\"O data structure is defined in \fI<sys/msg.h>\fP as follows:
83 .I msqid_ds
84 データ構造体は \fI<sys/msg.h>\fP で以下のように定義されている:
85 .nf
86 .in +4n
87
88 struct msqid_ds {
89 .\"O     struct ipc_perm msg_perm;     /* Ownership and permissions */
90 .\"O     time_t          msg_stime;    /* Time of last msgsnd(2) */
91 .\"O     time_t          msg_rtime;    /* Time of last msgrcv(2) */
92 .\"O     time_t          msg_ctime;    /* Time of last change */
93 .\"O     unsigned long   __msg_cbytes; /* Current number of bytes in
94 .\"O                                      queue (nonstandard) */
95 .\"O     msgqnum_t       msg_qnum;     /* Current number of messages
96 .\"O                                      in queue */
97 .\"O     msglen_t        msg_qbytes;   /* Maximum number of bytes
98 .\"O                                      allowed in queue */
99 .\"O     pid_t           msg_lspid;    /* PID of last msgsnd(2) */
100 .\"O     pid_t           msg_lrpid;    /* PID of last msgrcv(2) */
101     struct ipc_perm msg_perm;     /* 所有権と許可 */
102     time_t          msg_stime;    /* 最後の msgsnd(2) の時刻 */
103     time_t          msg_rtime;    /* 最後の msgrcv(2) の時刻 */
104     time_t          msg_ctime;    /* 最後に変更が行われた時刻 */
105     unsigned long   __msg_cbytes; /* キューにある現在のバイト数
106                                      (非標準) */
107     msgqnum_t       msg_qnum;     /* キューにある現在入っている
108                                      メッセージの数 */
109     msglen_t        msg_qbytes;   /* キューに許可されている
110                                      最大バイト数 */
111     pid_t           msg_lspid;    /* 最後の msgsnd(2) の PID */
112     pid_t           msg_lrpid;    /* 最後の msgrcv(2) の PID */
113 };
114 .in
115 .fi
116 .PP
117 .\"O The
118 .\"O .I ipc_perm
119 .\"O structure is defined in \fI<sys/ipc.h>\fP as follows
120 .\"O (the highlighted fields are settable using
121 .\"O .BR IPC_SET ):
122 .I ipc_perm
123 構造体は \fI<sys/ipc.h>\fP で以下のように定義されている
124 (強調されたフィールドは
125 .B IPC_SET
126 を使って設定可能である):
127 .PP
128 .nf
129 .in +4n
130 struct ipc_perm {
131 .\"O     key_t          __key;       /* Key supplied to msgget(2) */
132 .\"O     uid_t          \fBuid\fP;         /* Effective UID of owner */
133 .\"O     gid_t          \fBgid\fP;         /* Effective GID of owner */
134 .\"O     uid_t          cuid;        /* Effective UID of creator */
135 .\"O     gid_t          cgid;        /* Effective GID of creator */
136 .\"O     unsigned short \fBmode\fP;        /* Permissions */
137 .\"O     unsigned short __seq;       /* Sequence number */
138     key_t          __key;       /* msgget(2) に与えるキー */
139     uid_t          \fBuid\fP;         /* 所有者の実効 UID */
140     gid_t          \fBgid\fP;         /* 所有者の実効 GID */
141     uid_t          cuid;        /* 作成者の実効 UID */
142     gid_t          cgid;        /* 作成者の実効 GID */
143     unsigned short \fBmode\fP;        /* 許可 */
144     unsigned short __seq;       /* シーケンス番号 */
145 };
146 .in
147 .fi
148 .PP
149 .\"O Valid values for
150 .\"O .I cmd
151 .\"O are:
152 .I cmd
153 として有効な値は:
154 .TP
155 .B IPC_STAT
156 .\"O Copy information from the kernel data structure associated with
157 .\"O .I msqid
158 .\"O into the
159 .\"O .I msqid_ds
160 .\"O structure pointed to by
161 .\"O .IR buf .
162 .\"O The caller must have read permission on the message queue.
163 .I msqid
164 に関連づけられたメッセージ・キュー・データ構造体から、ポインタ
165 .I buf
166 が指し示す
167 .I msqid_ds
168 構造体に情報をコピーする。
169 呼び出し側はメッセージ・キューに対する読み込み許可を持っていなければならない。
170 .TP
171 .B IPC_SET
172 .\"O Write the values of some members of the
173 .\"O .I msqid_ds
174 .\"O structure pointed to by
175 .\"O .I buf
176 .\"O to the kernel data structure associated with this message queue,
177 .\"O updating also its
178 .\"O .I msg_ctime
179 .\"O member.
180 ポインタ
181 .I buf
182 が指し示す
183 .I msqid_ds
184 構造体のメンバーの値を、メッセージ・キューに関連づけられた
185 カーネル・データ構造体に書き込み、
186 .I msg_ctime
187 メンバーも更新する。
188 .\"O The following members of the structure are updated:
189 構造体のメンバーのうち、更新されるものを以下に示す:
190 .\"O .IR msg_qbytes ,
191 .\"O .IR msg_perm.uid ,
192 .\"O .IR msg_perm.gid ,
193 .\"O and (the least significant 9 bits of)
194 .\"O .IR msg_perm.mode .
195 .IR msg_qbytes ,
196 .IR msg_perm.uid ,
197 .IR msg_perm.gid ,
198 .I msg_perm.mode
199 (の下位 9 ビット)。
200 .\"O The effective UID of the calling process must match the owner
201 .\"O .RI ( msg_perm.uid )
202 .\"O or creator
203 .\"O .RI ( msg_perm.cuid )
204 .\"O of the message queue, or the caller must be privileged.
205 呼び出したプロセスの実効ユーザ ID が、メッセージ・キューの所有者
206 .RI ( msg_perm.uid )
207 または作成者
208 .RI ( msg_perm.cuid )
209 と一致するか、呼び出し元が特権を持たなければならない。
210 .\"O Appropriate privilege (Linux: the
211 .\"O .B CAP_IPC_RESOURCE
212 .\"O capability) is required to raise the
213 .\"O .I msg_qbytes
214 .\"O value beyond the system parameter
215 .\"O .BR MSGMNB .
216 .I msg_qbytes
217 をシステム・パラメータの
218 .B MSGMNB
219 を超えて設定するには、適切な特権 (Linux では
220 .B CAP_IPC_RESOURCE
221 ケーパビリティ (capability)) が必要である。
222 .TP
223 .B IPC_RMID
224 .\"O Immediately remove the message queue,
225 .\"O awakening all waiting reader and writer processes (with an error
226 .\"O return and
227 .\"O .I errno
228 .\"O set to
229 .\"O .BR EIDRM ).
230 メッセージ・キューをただちに削除する。
231 同時にその構造体の読み書きの待ち状態にあったプロセスに通知する
232 (エラーが返り、
233 .I errno
234
235 .B EIDRM
236 に設定される)。
237 .\"O The calling process must have appropriate privileges
238 .\"O or its effective user ID must be either that of the creator or owner
239 .\"O of the message queue.
240 呼び出したプロセスが適切な特権を持っているか、
241 呼び出したプロセスの実効ユーザ ID がメッセージ・キューの作成者か
242 所有者の実効ユーザ ID でなければならない。
243 .TP
244 .\"O .BR IPC_INFO " (Linux-specific)"
245 .BR IPC_INFO " (Linux 固有)"
246 .\"O Returns information about system-wide message queue limits and
247 .\"O parameters in the structure pointed to by
248 .\"O .IR buf .
249 システム全体でのメッセージ・キューの制限とパラメータに関する情報を、
250 .I buf
251 が指す構造体に入れて返す。
252 .\"O This structure is of type
253 .\"O .I msginfo
254 .\"O (thus, a cast is required),
255 .\"O defined in
256 .\"O .I <sys/msg.h>
257 .\"O if the
258 .\"O .B _GNU_SOURCE
259 .\"O feature test macro is defined:
260 この構造体は
261 .I msginfo
262 型である (そのためキャストが必要である)。
263 .I msginfo
264
265 .B _GNU_SOURCE
266 機能検査マクロが定義された場合に
267 .I <sys/msg.h>
268 で以下のように定義される:
269 .nf
270 .in +4n
271
272 struct msginfo {
273 .\"O     int msgpool; /* Size in kibibytes of buffer pool
274 .\"O                     used to hold message data;
275 .\"O                     unused within kernel */
276 .\"O     int msgmap;  /* Maximum number of entries in message
277 .\"O                     map; unused within kernel */
278 .\"O     int msgmax;  /* Maximum number of bytes that can be
279 .\"O                     written in a single message */
280 .\"O     int msgmnb;  /* Maximum number of bytes that can be
281 .\"O                     written to queue; used to initialize
282 .\"O                     msg_qbytes during queue creation
283 .\"O                     (msgget(2)) */
284 .\"O     int msgmni;  /* Maximum number of message queues */
285 .\"O     int msgssz;  /* Message segment size;
286 .\"O                     unused within kernel */
287 .\"O     int msgtql;  /* Maximum number of messages on all queues
288 .\"O                     in system; unused within kernel */
289 .\"O     unsigned short int msgseg;
290 .\"O                  /* Maximum number of segments;
291 .\"O                     unused within kernel */
292     int msgpool; /* メッセージ・データの保持に使用される
293                     バッファ・プールの大きさ (1024 バイト単位);
294                     カーネル内では未使用 */
295     int msgmap;  /* メッセージ・マップの最大エントリ数;
296                     カーネル内では未使用 */
297     int msgmax;  /* 一つのメッセージに書き込み可能な
298                     最大バイト数 */
299     int msgmnb;  /* 一つのキューに書き込み可能な最大バイト数;
300                     (msgget(2) での) キュー作成中の msg_qbytes
301                     の初期化に使用される */
302     int msgmni;  /* メッセージ・キューの数の最大値 */
303     int msgssz;  /* メッセージ・セグメントのサイズ;
304                     カーネル内では未使用 */
305     int msgtql;  /* システム上の全キューの最大メッセージ数;
306                     カーネル内では未使用 */
307     unsigned short int msgseg;
308                  /* 最大セグメント数; カーネル内では未使用 */
309 };
310
311 .in
312 .fi
313 .\"O The
314 .\"O .IR msgmni ,
315 .\"O .IR msgmax ,
316 .\"O and
317 .\"O .I msgmnb
318 .\"O settings can be changed via
319 .\"O .I /proc
320 .\"O files of the same name; see
321 .\"O .BR proc (5)
322 .\"O for details.
323 設定
324 .I msgmni ,
325 .I msgmax ,
326 .I msgmnb
327
328 .I /proc
329 にある同じ名前のファイル経由で変更可能である。
330 詳しくは
331 .BR proc (5)
332 を参照。
333 .TP
334 .\"O .BR MSG_INFO " (Linux-specific)"
335 .BR MSG_INFO " (Linux 固有)"
336 .\"O Returns a
337 .\"O .I msginfo
338 .\"O structure containing the same information as for
339 .\"O .BR IPC_INFO ,
340 .\"O except that the following fields are returned with information
341 .\"O about system resources consumed by message queues: the
342 .\"O .I msgpool
343 .\"O field returns the number of message queues that currently exist
344 .\"O on the system; the
345 .\"O .I msgmap
346 .\"O field returns the total number of messages in all queues
347 .\"O on the system; and the
348 .\"O .I msgtql
349 .\"O field returns the total number of bytes in all messages
350 .\"O in all queues on the system.
351 .B IPC_INFO
352 のときと同じ情報を格納した
353 .I msginfo
354 構造体を返す。
355 但し、以下のフィールドにはメッセージ・キューが
356 消費しているシステム資源に関する情報が格納される点が異なる。
357 .I msgpool
358 フィールドは現在システム上に存在するメッセージ・キューの数を返す。
359 .I msgmap
360 フィールドはシステム上の全てのキューに入っているメッセージ総数を返す。
361 .I msgtql
362 フィールドはシステム上の全てのキューに入っている全メッセージの
363 総バイト数を返す。
364 .TP
365 .\"O .BR MSG_STAT " (Linux-specific)"
366 .BR MSG_STAT " (Linux 固有)"
367 .\"O Returns a
368 .\"O .I msqid_ds
369 .\"O structure as for
370 .\"O .BR IPC_STAT .
371 .B IPC_STAT
372 と同じく
373 .I msqid_ds
374 構造体を返す。
375 .\"O However, the
376 .\"O .I msqid
377 .\"O argument is not a queue identifier, but instead an index into
378 .\"O the kernel's internal array that maintains information about
379 .\"O all message queues on the system.
380 但し、
381 .I msqid
382 引き数は、キュー識別子ではなく、システム上の全てのメッセージ・キュー
383 に関する情報を管理するカーネルの内部配列へのインデックスである。
384 .\"O .SH "RETURN VALUE"
385 .SH 返り値
386 .\"O On success,
387 .\"O .BR IPC_STAT ,
388 .\"O .BR IPC_SET ,
389 .\"O and
390 .\"O .B IPC_RMID
391 .\"O return 0.
392 成功すると、
393 .BR IPC_STAT ,
394 .BR IPC_SET ,
395 .B IPC_RMID
396 は 0 を返す。
397 .\"O A successful
398 .\"O .B IPC_INFO
399 .\"O or
400 .\"O .B MSG_INFO
401 .\"O operation returns the index of the highest used entry in the
402 .\"O kernel's internal array recording information about all
403 .\"O message queues.
404 .B IPC_INFO
405
406 .B MSG_INFO
407 操作は、成功すると、全てのメッセージ・キューに関する情報を
408 管理しているカーネルの内部配列の使用中エントリのインデックスの
409 うち最大値を返す
410 .\"O (This information can be used with repeated
411 .\"O .B MSG_STAT
412 .\"O operations to obtain information about all queues on the system.)
413 (この情報は、システムの全てのメッセージ・キューに関する情報を
414 取得するために、
415 .B MSG_STAT
416 操作を繰り返し実行する際に使用できる)。
417 .\"O A successful
418 .\"O .B MSG_STAT
419 .\"O operation returns the identifier of the queue whose index was given in
420 .\"O .IR msqid .
421 .B MSG_STAT
422 操作は、成功すると、
423 .I msqid
424 で指定されたインデックスを持つメッセージ・キューの識別子を返す。
425
426 .\"O On error, \-1 is returned with
427 .\"O .I errno
428 .\"O indicating the error.
429 エラーの場合は \-1 を返し、
430 .I errno
431 を適切に設定する。
432 .\"O .SH ERRORS
433 .SH エラー
434 .\"O On failure,
435 .\"O .I errno
436 .\"O is set to one of the following:
437 失敗した場合、
438 .I errno
439 は以下の値の中のどれか一つに設定される:
440 .TP
441 .B EACCES
442 .\"O The argument
443 .\"O .I cmd
444 .\"O is equal to
445 .\"O .B IPC_STAT
446 .\"O or
447 .\"O .BR MSG_STAT ,
448 .\"O but the calling process does not have read permission on the message queue
449 .\"O .IR msqid ,
450 .\"O and does not have the
451 .\"O .B CAP_IPC_OWNER
452 .\"O capability.
453 引き数
454 .I cmd
455
456 .B IPC_STAT
457 または
458 .B MSG_STAT
459 に等しいが、呼び出したプロセスがメッセージ・キュー
460 .I msqid
461 に対する読み込み許可を持っておらず、かつ
462 .B CAP_IPC_OWNER
463 ケーパビリティを持っていない。
464 .TP
465 .B EFAULT
466 .\"O The argument
467 .\"O .I cmd
468 .\"O has the value
469 .\"O .B IPC_SET
470 .\"O or
471 .\"O .BR IPC_STAT ,
472 .\"O but the address pointed to by
473 .\"O .I buf
474 .\"O isn't accessible.
475 引き数
476 .I cmd
477
478 .B IPC_SET
479
480 .B IPC_STAT
481 で、ポインタ
482 .I buf
483 で指されているアドレスがアクセス可能でない。
484 .TP
485 .B EIDRM
486 .\"O The message queue was removed.
487 メッセージ・キューが削除された。
488 .TP
489 .B EINVAL
490 .\"O Invalid value for
491 .\"O .I cmd
492 .\"O or
493 .\"O .IR msqid .
494 .\"O Or: for a
495 .\"O .B MSG_STAT
496 .\"O operation, the index value specified in
497 .\"O .I msqid
498 .\"O referred to an array slot that is currently unused.
499 .I cmd
500 または
501 .I msqid
502 に不正な値が設定された。
503 もしくは、
504 .B MSG_STAT
505 操作の場合に、
506 .I msqid
507 で指定されたインデックス値が現在未使用の配列のスロットを参照いていた。
508 .TP
509 .B EPERM
510 .\"O The argument
511 .\"O .I cmd
512 .\"O has the value
513 .\"O .B IPC_SET
514 .\"O or
515 .\"O .BR IPC_RMID ,
516 .\"O but the effective user ID of the calling process is not the creator
517 .\"O (as found in
518 .\"O .IR msg_perm.cuid )
519 .\"O or the owner
520 .\"O (as found in
521 .\"O .IR msg_perm.uid )
522 .\"O of the message queue,
523 .\"O and the process is not privileged (Linux: it does not have the
524 .\"O .B CAP_SYS_ADMIN
525 .\"O capability).
526 引き数
527 .I cmd
528
529 .B IPC_SET
530
531 .B IPC_RMID
532 であるが、呼び出したプロセスの実効ユーザ ID がメッセージキューの
533 .RI ( msg_perm.cuid
534 として見つかる) 作成者
535
536 .RI ( msg_perm.uid
537 として見つかる) 所有者のいずれでもなく、
538 かつ呼び出したプロセスに特権 (Linux では
539 .B CAP_SYS_ADMIN
540 ケーパビリティ) がない。
541 .\"O .SH "CONFORMING TO"
542 .SH 準拠
543 SVr4, POSIX.1-2001.
544 .\"O .\" SVID does not document the EIDRM error condition.
545 .\" SVID には EIDRM エラーについての記述はない。
546 .\"O .SH NOTES
547 .SH 注意
548 .\"O The
549 .\"O .BR IPC_INFO ,
550 .\"O .B MSG_STAT
551 .\"O and
552 .\"O .B MSG_INFO
553 .\"O operations are used by the
554 .\"O .BR ipcs (1)
555 .\"O program to provide information on allocated resources.
556 .\"O In the future these may modified or moved to a /proc file system
557 .\"O interface.
558 .BR IPC_INFO ,
559 .BR MSG_STAT ,
560 .B MSG_INFO
561 操作は、
562 .BR ipcs (1)
563 プログラムで割り当て済の資源に関する情報を提供するために
564 使用されている。将来、これらの操作は変更されたり、
565 /proc ファイルシステムのインタフェースに移動されるかもしれない。
566
567
568 .\"O Various fields in the \fIstruct msqid_ds\fP were
569 .\"O typed as
570 .\"O .I short
571 .\"O under Linux 2.2
572 .\"O and have become
573 .\"O .I long
574 .\"O under Linux 2.4.
575 .\"O To take advantage of this,
576 .\"O a recompilation under glibc-2.1.91 or later should suffice.
577 .\"O (The kernel distinguishes old and new calls by an
578 .\"O .B IPC_64
579 .\"O flag in
580 .\"O .IR cmd .)
581 \fIstruct msqid_ds\fP 内の多くのフィールドは、
582 Linux 2.2 では
583 .I short
584 だったが、Linux 2.4 では
585 .I long
586 になった。
587 この利点を生かすには、glibc-2.1.91 以降の環境下で
588 再コンパイルすれば十分である。
589 (カーネルは新しい形式の呼び出しと古い形式の呼び出しを
590 .I cmd
591 内の
592 .B IPC_64
593 フラグで区別する。)
594 .\"O .SH "SEE ALSO"
595 .SH 関連項目
596 .BR msgget (2),
597 .BR msgrcv (2),
598 .BR msgsnd (2),
599 .BR capabilities (7),
600 .BR mq_overview (7),
601 .BR svipc (7)