MSGCTL
Section: Linux Programmer's Manual (2)
Updated: 2020-11-01
Index
JM Home Page
roff page
名前
msgctl - System V メッセージ制御操作
書式
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>
int msgctl(int msqid, int cmd, struct msqid_ds *buf);
説明
msgctl() はメッセージキュー識別子 msqid で指定された System V メッセージキュー (message queue)
に対して cmd で指定された制御操作を行なう。
msqid_ds データ構造体は <sys/msg.h> で以下のように定義されている:
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) */
};
msgid_ds 構造体のフィールドは以下の通りである:
- msg_perm
-
This is an ipc_perm structure (see below) that specifies the access
permissions on the message queue.
- msg_stime
-
最後の msgsnd(2) システムコールの時刻。
- msg_rtime
-
最後の msgrcv(2) システムコールの時刻。
- msg_ctime
-
Time of creation of queue or time of last msgctl() IPC_SET operation.
- msg_cbytes
-
Number of bytes in all messages currently on the message queue. This is a
nonstandard Linux extension that is not specified in POSIX.
- msg_qnum
-
Number of messages currently on the message queue.
- msg_qbytes
-
Maximum number of bytes of message text allowed on the message queue.
- msg_lspid
-
最後の msgsnd(2) システムコールを実行したプロセスの ID。
- msg_lrpid
-
最後の msgrcv(2) システムコールを実行したプロセスの ID。
ipc_perm 構造体は以下のように定義されている (強調されたフィールドは IPC_SET を使って設定可能である):
struct ipc_perm {
key_t __key; /* msgget(2) に与えるキー */
uid_t uid; /* 所有者の実効 UID */
gid_t gid; /* 所有者の実効 GID */
uid_t cuid; /* 作成者の実効 UID */
gid_t cgid; /* 作成者の実効 GID */
unsigned short mode; /* 許可 */
unsigned short __seq; /* シーケンス番号 */
};
The least significant 9 bits of the mode field of the ipc_perm
structure define the access permissions for the message queue. The
permission bits are as follows:
0400 | ユーザーによる読み出し
|
0200 | ユーザーによる書き込み
|
0040 | グループによる読み出し
|
0020 | グループによる書き込み
|
0004 | 他人 (others) による読み出し
|
0002 | 他人 (others) による書き込み
|
ビット 0100, 0010, 0001 (実行ビット) をシステムは使用しない。
cmd として有効な値は:
- IPC_STAT
-
msqid に関連づけられたメッセージキューデータ構造体から、ポインター buf が指し示す msqid_ds
構造体に情報をコピーする。 呼び出し側はメッセージキューに対する読み込み許可を持っていなければならない。
- IPC_SET
-
Write the values of some members of the msqid_ds structure pointed to by
buf to the kernel data structure associated with this message queue,
updating also its msg_ctime member.
-
The following members of the structure are updated: msg_qbytes,
msg_perm.uid, msg_perm.gid, and (the least significant 9 bits of)
msg_perm.mode.
-
The effective UID of the calling process must match the owner
(msg_perm.uid) or creator (msg_perm.cuid) of the message queue, or
the caller must be privileged. Appropriate privilege (Linux: the
CAP_SYS_RESOURCE capability) is required to raise the msg_qbytes value
beyond the system parameter MSGMNB.
- IPC_RMID
-
メッセージキューをただちに削除する。 同時にその構造体の読み書きの待ち状態にあったプロセスに通知する (エラーが返り、 errno が
EIDRM に設定される)。 呼び出したプロセスが適切な特権を持っているか、 呼び出したプロセスの実効ユーザー ID がメッセージキューの作成者か
所有者の実効ユーザー ID でなければならない。この場合、 msgctl() の第 3 引数は無視される。
- IPC_INFO (Linux 固有)
-
システム全体でのメッセージキューの制限とパラメーターに関する情報を、 buf が指す構造体に入れて返す。 この構造体は msginfo
型である (そのためキャストが必要である)。 msginfo は _GNU_SOURCE 機能検査マクロが定義された場合に
<sys/msg.h> で以下のように定義される:
-
struct msginfo {
int msgpool; /* メッセージデータの保持に使用される
バッファープールの大きさ (1024 バイト単位);
カーネル内では未使用 */
int msgmap; /* メッセージマップの最大エントリー数;
カーネル内では未使用 */
int msgmax; /* 一つのメッセージに書き込み可能な
最大バイト数 */
int msgmnb; /* 一つのキューに書き込み可能な最大バイト数;
(msgget(2) での) キュー作成中の msg_qbytes
の初期化に使用される */
int msgmni; /* メッセージキューの数の最大値 */
int msgssz; /* メッセージセグメントのサイズ;
カーネル内では未使用 */
int msgtql; /* システム上の全キューの最大メッセージ数;
カーネル内では未使用 */
unsigned short msgseg;
/* 最大セグメント数; カーネル内では未使用 */
};
-
設定 msgmni , msgmax , msgmnb は /proc にある同じ名前のファイル経由で変更可能である。 詳しくは
proc(5) を参照。
- MSG_INFO (Linux 固有)
-
IPC_INFO のときと同じ情報を格納した msginfo 構造体を返す。 但し、以下のフィールドにはメッセージキューが
消費しているシステム資源に関する情報が格納される点が異なる。 msgpool フィールドは現在システム上に存在するメッセージキューの数を返す。
msgmap フィールドはシステム上の全てのキューに入っているメッセージ総数を返す。 msgtql
フィールドはシステム上の全てのキューに入っている全メッセージの 総バイト数を返す。
- MSG_STAT (Linux 固有)
-
IPC_STAT と同じく msqid_ds 構造体を返す。 但し、 msqid
引数は、キュー識別子ではなく、システム上の全てのメッセージキュー に関する情報を管理するカーネルの内部配列へのインデックスである。
- MSG_STAT_ANY (Linux 固有, Linux 4.17 以降)
-
Return a msqid_ds structure as for MSG_STAT. However,
msg_perm.mode is not checked for read access for msqid meaning that
any user can employ this operation (just as any user may read
/proc/sysvipc/msg to obtain the same information).
返り値
On success, IPC_STAT, IPC_SET, and IPC_RMID return 0. A successful
IPC_INFO or MSG_INFO 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 MSG_STAT or
MSG_STAT_ANY operations to obtain information about all queues on the
system.) A successful MSG_STAT or MSG_STAT_ANY operation returns the
identifier of the queue whose index was given in msqid.
エラーの場合は -1 を返し、 errno を適切に設定する。
エラー
失敗した場合、 errno は以下の値の中のどれか一つに設定される:
- EACCES
-
The argument cmd is equal to IPC_STAT or MSG_STAT, but the calling
process does not have read permission on the message queue msqid, and
does not have the CAP_IPC_OWNER capability in the user namespace that
governs its IPC namespace.
- EFAULT
-
引数 cmd が IPC_SET か IPC_STAT で、ポインター buf で指されているアドレスがアクセス可能でない。
- EIDRM
-
メッセージキューが削除された。
- EINVAL
-
cmd または msqid に不正な値が設定された。 もしくは、 MSG_STAT 操作の場合に、 msqid
で指定されたインデックス値が現在未使用の配列のスロットを参照いていた。
- EPERM
-
引数 cmd が IPC_SET か IPC_RMID であるが、呼び出したプロセスの実効ユーザー ID がメッセージキューの
(msg_perm.cuid として見つかる) 作成者 と (msg_perm.uid として見つかる) 所有者のいずれでもなく、
かつ呼び出し者に特権がない (Linux では CAP_SYS_ADMIN ケーパビリティがない)。
- EPERM
-
IPC_SET で msg_qbytes をシステムパラメーター MSGMNB
より大きな値に設定しようとしたが、呼び出し元が特権を持っていなかった (Linux では、 CAP_SYS_RESOURCE
ケーパビリティを持っていなかった)。
準拠
POSIX.1-2001, POSIX.1-2008, SVr4.
注意
Linux や POSIX の全てのバージョンでは、 <sys/types.h> と <sys/ipc.h>
のインクルードは必要ない。しかしながら、いくつかの古い実装ではこれらのヘッダーファイルのインクルードが必要であり、 SVID
でもこれらのインクルードをするように記載されている。このような古いシステムへの移植性を意図したアプリケーションではこれらのファイルをインクルードする必要があるかもしれない。
IPC_INFO, MSG_STAT, MSG_INFO 操作は、 ipcs(1)
プログラムで割り当て済の資源に関する情報を提供するために 使用されている。将来、これらの操作は変更されたり、 /proc
ファイルシステムのインターフェースに移動されるかもしれない。
struct msqid_ds 内の多くのフィールドは、 Linux 2.2 では short だったが、Linux 2.4 では
long になった。 この利点を生かすには、glibc-2.1.91 以降の環境下で 再コンパイルすれば十分である。
(カーネルは新しい形式の呼び出しと古い形式の呼び出しを cmd 内の IPC_64 フラグで区別する。)
関連項目
msgget(2), msgrcv(2), msgsnd(2), capabilities(7),
mq_overview(7), sysvipc(7)
この文書について
この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は
https://www.kernel.org/doc/man-pages/ に書かれている。
Index
- 名前
-
- 書式
-
- 説明
-
- 返り値
-
- エラー
-
- 準拠
-
- 注意
-
- 関連項目
-
- この文書について
-
This document was created by
man2html,
using the manual pages.
Time: 03:33:32 GMT, December 05, 2022