[linuxjm/LDP_man-pages.git] / draft / man7 / mq_overview.7

'\" t
.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" 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.
.\"
.\" Japanese Version Copyright (c) 2006 Akihiro MOTOKI all rights reserved.
.\" Translated 2006-03-13, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
.\" Updated 2006-07-20, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.36
.\" Updated 2009-02-23, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.19
.\" Updated 2010-04-11, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.24
.\"
.\"WORD:        message queue descriptor        メッセージキュー記述子
.\"WORD:        message queue description       メッセージキュー記述
.\"
.TH MQ_OVERVIEW 7 2009-09-27 "Linux" "Linux Programmer's Manual"
.\"O .SH NAME
.SH 名前
.\"O mq_overview \- Overview of POSIX message queues
mq_overview \- POSIX メッセージキューの概要
.\"O .SH DESCRIPTION
.SH 説明
.\"O POSIX message queues allow processes to exchange data in
.\"O the form of messages.
.\"O This API is distinct from that provided by System V message queues
.\"O .RB ( msgget (2),
.\"O .BR msgsnd (2),
.\"O .BR msgrcv (2),
.\"O etc.), but provides similar functionality.
POSIX メッセージキューを使用すると、プロセス間で
メッセージの形でのデータのやり取りを行うことができる。
この API は System V メッセージキューの API
.RB ( msgget (2),
.BR msgsnd (2),
.BR msgrcv (2)
など) とは異なるものだが、同様の機能を提供する。

.\"O Message queues are created and opened using
.\"O .BR mq_open (3);
.\"O this function returns a
.\"O .I message queue descriptor
.\"O .RI ( mqd_t ),
.\"O which is used to refer to the open message queue in later calls.
.\"O Each message queue is identified by a name of the form
.\"O .IR /somename ;
.\"O that is, a null-terminated string of up to
.\"O .BI NAME_MAX
.\"O (i.e., 255) characters consisting of an initial slash,
.\"O followed by one or more characters, none of which are slashes.
メッセージキューの作成とオープンは
.BR mq_open (3)
を使って行う。この関数は
.I メッセージキュー記述子 (message queue descriptor)
.RI ( mqd_t )
を返す。これ以降のコールでは、オープンされたメッセージキューは
.I メッセージキュー記述子
を使って参照される。
各メッセージキューは
.I /somename
の形の名前で区別することができる。
その名前は、最大で
.B NAME_MAX
(すなわち 255) 文字の NULL 終端された文字列で、
スラッシュで始まり、スラッシュ以外の文字が 1 文字以上続く形式である。
.\"O Two processes can operate on the same queue by passing the same name to
.\"O .BR mq_open (3).
.BR mq_open (3)
に同じ名前を渡すことで、2つのプロセスで同一のキューを
操作することができる。

.\"O Messages are transferred to and from a queue using
.\"O .BR mq_send (3)
.\"O and
.\"O .BR mq_receive (3).
.\"O When a process has finished using the queue, it closes it using
.\"O .BR mq_close (3),
.\"O and when the queue is no longer required, it can be deleted using
.\"O .BR mq_unlink (3).
.\"O Queue attributes can be retrieved and (in some cases) modified using
.\"O .BR mq_getattr (3)
.\"O and
.\"O .BR mq_setattr (3).
.\"O A process can request asynchronous notification
.\"O of the arrival of a message on a previously empty queue using
.\"O .BR mq_notify (3).
メッセージのキューへの送受信は
.BR mq_send (3)
と
.BR mq_receive (3)
を使って行う。プロセスがキューの使用を終えるときには、
.BR mq_close (3)
を使ってキューをクローズする。キューがもはや不要となった場合には、
.BR mq_unlink (3)
を使ってキューを削除できる。キューの属性は
.BR mq_getattr (3)
で取得でき、 (制限はあるが)
.BR mq_setattr (3)
で変更できる。
.BR mq_notify (3)
を使うことで、空のキューへのメッセージ到着を非同期で
通知するように要求することもできる。

.\"O A message queue descriptor is a reference to an
.\"O .I "open message queue description"
.\"O (cf.
.\"O .BR open (2)).
.\"O After a
.\"O .BR fork (2),
.\"O a child inherits copies of its parent's message queue descriptors,
.\"O and these descriptors refer to the same open message queue descriptions
.\"O as the corresponding descriptors in the parent.
.\"O Corresponding descriptors in the two processes share the flags
.\"O .RI ( mq_flags )
.\"O that are associated with the open message queue description.
メッセージキュー記述子は
.I "オープンメッセージキュー記述 (open message queue description)"
への参照である
.RB ( open (2)
も参照)。
.BR fork (2)
実行後は、子プロセスは親プロセスのメッセージキュー記述子のコピーを継承する。
これらの記述子は、親プロセスの対応する記述子と同じオープンメッセージキュー
記述を参照している。親プロセスと子プロセスの対応する記述子は、フラグ
.RI ( mq_flags )
を共有する。なぜなら、フラグはオープンメッセージキュー記述に
関連付けられているからである。

.\"O Each message has an associated
.\"O .IR priority ,
.\"O and messages are always delivered to the receiving process
.\"O highest priority first.
.\"O Message priorities range from 0 (low) to
.\"O .I sysconf(_SC_MQ_PRIO_MAX)\ -\ 1
.\"O (high).
.\"O On Linux,
.\"O .I sysconf(_SC_MQ_PRIO_MAX)
.\"O returns 32768, but POSIX.1-2001 only requires
.\"O an implementation to support priorities in the range 0 to 31;
.\"O some implementations only provide this range.
各メッセージにはそれぞれ
.I 優先度 (priority)
があり、メッセージの受信プロセスへの配送は常に
優先度の高いメッセージから順に行われる。
メッセージの優先度は 0 (低優先) から
.I sysconf(_SC_MQ_PRIO_MAX)\ -\ 1
(高優先) の値を持つ。
Linux では、
.I sysconf(_SC_MQ_PRIO_MAX)
は 32768 を返すが、
POSIX.1-2001 で要求されているのは 0 から 31 までの優先度を
実装することだけであり、実装によってはこの範囲の優先度しか
対応していない。
.PP
.\"O The remainder of this section describes some specific details
.\"O of the Linux implementation of POSIX message queues.
この節の残りでは、POSIX メッセージキューの Linux の実装の詳細
について説明する。
.\"O .SS Library interfaces and system calls
.SS ライブラリインタフェースとシステムコール
.\"O In most cases the
.\"O .B mq_*()
.\"O library interfaces listed above are implemented
.\"O on top of underlying system calls of the same name.
.\"O Deviations from this scheme are indicated in the following table:
ほとんどの場合、上記の
.B mq_*()
ライブラリインタフェースは、同じ名前の下位層のシステムコールを
使って実装されている。この枠組みにあてはまらないものを
以下の表に示す。
.in +4n
.TS
lB lB
l l.
Library interface       System call
mq_close(3)     close(2)
mq_getattr(3)   mq_getsetattr(2)
mq_notify(3)    mq_notify(2)
mq_open(3)      mq_open(2)
mq_receive(3)   mq_timedreceive(2)
mq_send(3)      mq_timedsend(2)
mq_setattr(3)   mq_getsetattr(2)
mq_timedreceive(3)      mq_timedreceive(2)
mq_timedsend(3) mq_timedsend(2)
mq_unlink(3)    mq_unlink(2)
.TE
.in
.\"O .SS Versions
.SS バージョン
.\"O POSIX message queues have been supported on Linux since kernel 2.6.6.
.\"O Glibc support has been provided since version 2.3.4.
Linux では POSIX メッセージキューはカーネル 2.6.6 以降でサポートされている。
glibc ではバージョン 2.3.4 以降でサポートされている。
.\"O .SS Kernel configuration
.SS カーネルの設定
.\"O Support for POSIX message queues is configurable via the
.\"O .B CONFIG_POSIX_MQUEUE
.\"O kernel configuration option.
.\"O This option is enabled by default.
POSIX メッセージキューのサポートは、カーネルの設定 (configuration)
オプション
.B CONFIG_POSIX_MQUEUE
で設定可能である。このオプションはデフォルトでは有効である。
.\"O .SS Persistence
.SS 持続性
.\"O POSIX message queues have kernel persistence:
.\"O if not removed by
.\"O .BR mq_unlink (3),
.\"O a message queue will exist until the system is shut down.
POSIX メッセージキューはカーネル内で保持される。
.BR mq_unlink (3)
で削除されなければ、メッセージキューは
システムがシャットダウンされるまで存在し続ける。
.\"O .SS Linking
.SS リンク
.\"O Programs using the POSIX message queue API must be compiled with
.\"O .I cc \-lrt
.\"O to link against the real-time library,
.\"O .IR librt .
POSIX メッセージキュー API を使用したプログラムは
.I cc \-lrt
でコンパイルし、リアルタイムライブラリ
.I librt
とリンクしなければならない。
.\"O .SS /proc interfaces
.SS /proc インタフェース
.\"O The following interfaces can be used to limit the amount of
.\"O kernel memory consumed by POSIX message queues:
以下のインタフェースを使って、POSIX メッセージキューが消費するカーネル
メモリの量を制限することができる。
.TP
.I /proc/sys/fs/mqueue/msg_max
.\"O This file can be used to view and change the ceiling value for the
.\"O maximum number of messages in a queue.
.\"O This value acts as a ceiling on the
.\"O .I attr\->mq_maxmsg
.\"O argument given to
.\"O .BR mq_open (3).
.\"O The default value for
.\"O .I msg_max
.\"O is 10.
.\"O The minimum value is 1 (10 in kernels before 2.6.28).
.\"O The upper limit is
.\"O .BR HARD_MAX :
.\"O .IR "(131072\ /\ sizeof(void\ *))"
.\"O (32768 on Linux/86).
.\"O This limit is ignored for privileged processes
.\"O .RB ( CAP_SYS_RESOURCE ),
.\"O but the
.\"O .B HARD_MAX
.\"O ceiling is nevertheless imposed.
このファイルを使って、一つのキューに入れられるメッセージの最大数の
上限値を参照したり変更したりできる。この値は、
.BR mq_open (3)
に渡す
.I attr\->mq_maxmsg
引き数に対する上限値として機能する。
.I msg_max
のデフォルト値は 10 で、
最小値は 1 (2.6.28 より前のカーネルでは 10) である。
上限は「埋め込みの固定値」
.RB ( HARD_MAX )
で
.IR "(131072\ /\ sizeof(void\ *))"
(Linux/86 では 32768) である。
この上限は特権プロセス
.RB ( CAP_SYS_RESOURCE )
では無視されるが、埋め込みの固定値による上限は
どんな場合にでも適用される。
.TP
.I /proc/sys/fs/mqueue/msgsize_max
.\"O This file can be used to view and change the ceiling on the
.\"O maximum message size.
.\"O This value acts as a ceiling on the
.\"O .I attr\->mq_msgsize
.\"O argument given to
.\"O .BR mq_open (3).
.\"O The default value for
.\"O .I msgsize_max
.\"O is 8192 bytes.
.\"O The minimum value is 128 (8192 in kernels before 2.6.28).
.\"O The upper limit for
.\"O .I msgsize_max
.\"O is 1,048,576 (in kernels before 2.6.28, the upper limit was
.\"O .BR INT_MAX ;
.\"O that is, 2,147,483,647 on Linux/86).
.\"O This limit is ignored for privileged processes
.\"O .RB ( CAP_SYS_RESOURCE ).
このファイルを使って、メッセージの最大サイズの上限値を       
参照したり変更したりできる。      
この値は、 
.BR mq_open (3) 
に渡す       
.I attr\->mq_msgsize
引き数に対する上限値として機能する。  
.I msgsize_max  
のデフォルト値は 8192 バイトで、
最小値は 128 (2.6.28 より前のカーネルでは 8192) である。
.I msgsize_max
の上限は 1,048,576 である
(2.6.28 より前のカーネルでは、上限は
.B INT_MAX
(Linux/86 では 2,147,483,647) であった)。
この上限は特権プロセス       
.RB ( CAP_SYS_RESOURCE )        
では無視される。
.TP
.I /proc/sys/fs/mqueue/queues_max
.\"O This file can be used to view and change the system-wide limit on the
.\"O number of message queues that can be created.
.\"O Only privileged processes
.\"O .RB ( CAP_SYS_RESOURCE )
.\"O can create new message queues once this limit has been reached.
.\"O The default value for
.\"O .I queues_max
.\"O is 256; it can be changed to any value in the range 0 to INT_MAX.
このファイルを使って、作成することができるメッセージキューの数に        
対するシステム全体での制限を参照したり変更したりできる。    
一度この上限に達すると、新しいメッセージキューを作成できるのは   
特権プロセス      
.RB ( CAP_SYS_RESOURCE )        
だけとなる。      
.I queues_max   
のデフォルト値は 256 であり、       
0 から INT_MAX の範囲の任意の値に変更することができる。
.\"O .SS Resource limit
.SS リソース制限
.\"O The
.\"O .B RLIMIT_MSGQUEUE
.\"O resource limit, which places a limit on the amount of space
.\"O that can be consumed by all of the message queues
.\"O belonging to a process's real user ID, is described in
.\"O .BR getrlimit (2).
リソース上限
.B RLIMIT_MSGQUEUE
は、プロセスの実 UID に対応する全メッセージキューが消費する
メモリ空間の量に対して上限を設定する。
.BR getrlimit (2)
を参照。
.\"O .SS Mounting the message queue file system
.SS メッセージキュー・ファイルシステムのマウント
.\"O On Linux, message queues are created in a virtual file system.
.\"O (Other implementations may also provide such a feature,
.\"O but the details are likely to differ.)
.\"O This file system can be mounted (by the superuser) using the following
.\"O commands:
Linux では、メッセージキューは仮想ファイルシステム内に作成される
(他の実装でも同様の機能が提供されているものもあるが、
詳細は違っているだろう)。
以下のコマンドを使うことで (スーパーユーザは)
このファイルシステムをマウントできる:
.in +4n
.nf

.RB "#" " mkdir /dev/mqueue"
.RB "#" " mount \-t mqueue none /dev/mqueue"

.fi
.in
.\"O The sticky bit is automatically enabled on the mount directory.
マウントしたディレクトリのスティッキービット (sticky bit) は
自動的にオンとなる。

.\"O After the file system has been mounted, the message queues on the system
.\"O can be viewed and manipulated using the commands usually used for files
.\"O (e.g.,
.\"O .BR ls (1)
.\"O and
.\"O .BR rm (1)).
メッセージキュー・ファイルシステムのマウント後は、ファイルに対して
通常使うコマンド (例えば
.BR ls (1)
や
.BR rm (1))
を使って、システム上のメッセージキューを表示したり
操作したりできる。

.\"O The contents of each file in the directory consist of a single line
.\"O containing information about the queue:
ディレクトリ内の各ファイルの内容は 1行であり、
キューに関する情報が表示される。
.in +4n
.nf

.RB "$" " cat /dev/mqueue/mymq"
QSIZE:129     NOTIFY:2    SIGNO:0    NOTIFY_PID:8260

.fi
.in
.\"O These fields are as follows:
各フィールドの詳細は以下の通りである:
.TP
.B QSIZE
.\"O Number of bytes of data in all messages in the queue.
キューに入っている全メッセージの合計バイト数。
.TP
.B NOTIFY_PID
.\"O If this is nonzero, then the process with this PID has used
.\"O .BR mq_notify (3)
.\"O to register for asynchronous message notification,
.\"O and the remaining fields describe how notification occurs.
この値が 0 以外の場合、この値の PID を持つプロセスが
.BR mq_notify (3)
を使って、非同期のメッセージ通知を行うように設定したことを示す。
どのように通知が行われるかは、以下のフィールドにより決定される。
.TP
.B NOTIFY
.\"O Notification method:
.\"O 0 is
.\"O .BR SIGEV_SIGNAL ;
.\"O 1 is
.\"O .BR SIGEV_NONE ;
.\"O and
.\"O 2 is
.\"O .BR SIGEV_THREAD .
通知方法:
0 は
.BR SIGEV_SIGNAL ;
1 は
.BR SIGEV_NONE ;
2 は
.B SIGEV_THREAD
.TP
.B SIGNO
.\"O Signal number to be used for
.\"O .BR SIGEV_SIGNAL .
.B SIGEV_SIGNAL
に使用されるシグナル番号。
.\"O .SS Polling message queue descriptors
.SS メッセージキュー記述子のポーリング
.\"O On Linux, a message queue descriptor is actually a file descriptor,
.\"O and can be monitored using
.\"O .BR select (2),
.\"O .BR poll (2),
.\"O or
.\"O .BR epoll (7).
.\"O This is not portable.
Linux では、メッセージキュー記述子は実際はファイル記述子 (file descriptor)
であり、
.BR select (2),
.BR poll (2),
.BR epoll (7)
を使って監視することができる。
この機能の移植性はない。
.\"O .SH "CONFORMING TO"
.SH 準拠
POSIX.1-2001.
.\"O .SH NOTES
.SH 注意
.\"O System V message queues
.\"O .RB ( msgget (2),
.\"O .BR msgsnd (2),
.\"O .BR msgrcv (2),
.\"O etc.) are an older API for exchanging messages between processes.
.\"O POSIX message queues provide a better designed interface than
.\"O System V message queues;
.\"O on the other hand POSIX message queues are less widely available
.\"O (especially on older systems) than System V message queues.
System V メッセージキュー
.RB ( msgget (2),
.BR msgsnd (2),
.BR msgrcv (2)
など) はプロセス間でメッセージをやり取りするための古い API である。
POSIX メッセージキューは System V メッセージキューよりもうまく
設計されたインタフェースを提供している。
一方で、POSIX メッセージキューは System V メッセージキューと比べると
利用できるシステムが少ない (特に、古いシステムでは少ない)。

.\"O Linux does not currently (2.6.26) support the use of access control
.\"O lists (ACLs) for POSIX message queues.
現在のことろ (バージョン 2.6.26 時点)、
Linux は POSIX メッセージキューに対するアクセス制御リスト (ACL) に
対応していない。
.\"O .SH EXAMPLE
.SH 例
.\"O An example of the use of various message queue functions is shown in
.\"O .BR mq_notify (3).
各種のメッセージキュー関数を使用した例が
.BR mq_notify (3)
に記載されている。
.\"O .SH "SEE ALSO"
.SH 関連項目
.BR getrlimit (2),
.BR mq_getsetattr (2),
.BR poll (2),
.BR select (2),
.BR mq_close (3),
.BR mq_getattr (3),
.BR mq_notify (3),
.BR mq_open (3),
.BR mq_receive (3),
.BR mq_send (3),
.BR mq_unlink (3),
.BR epoll (7)