draft/man2/shmctl.2

   1 .\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993
   2 .\" and Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
   3 .\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .\" Modified 1993-07-28, Rik Faith <faith@cs.unc.edu>
  28 .\" Modified 1993-11-28, Giorgio Ciucci <giorgio@crcc.it>
  29 .\" Modified 1997-01-31, Eric S. Raymond <esr@thyrsus.com>
  30 .\" Modified 2001-02-18, Andries Brouwer <aeb@cwi.nl>
  31 .\" Modified 2002-01-05, 2004-05-27, 2004-06-17,
  32 .\"    Michael Kerrisk <mtk.manpages@gmail.com>
  33 .\" Modified 2004-10-11, aeb
  34 .\" Modified, Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  35 .\"     Language and formatting clean-ups
  36 .\"     Updated shmid_ds structure definitions
  37 .\"     Added information on SHM_DEST and SHM_LOCKED flags
  38 .\"     Noted that CAP_IPC_LOCK is not required for SHM_UNLOCK
  39 .\"             since kernel 2.6.9
  40 .\" Modified, 2004-11-25, mtk, notes on 2.6.9 RLIMIT_MEMLOCK changes
  41 .\" 2005-04-25, mtk -- noted aberrant Linux behavior w.r.t. new
  42 .\"     attaches to a segment that has already been marked for deletion.
  43 .\" 2005-08-02, mtk: Added IPC_INFO, SHM_INFO, SHM_STAT descriptions.
  44 .\"
  45 .\"*******************************************************************
  46 .\"
  47 .\" This file was generated with po4a. Translate the source file.
  48 .\"
  49 .\"*******************************************************************
  50 .TH SHMCTL 2 2013\-03\-18 Linux "Linux Programmer's Manual"
  51 .SH 名前
  52 shmctl \- System V 共有メモリ (shared memory) を制御する
  53 .SH 書式
  54 .ad l
  55 \fB#include <sys/ipc.h>\fP
  56 .br
  57 \fB#include <sys/shm.h>\fP
  58 .sp
  59 \fBint shmctl(int \fP\fIshmid\fP\fB, int \fP\fIcmd\fP\fB, struct shmid_ds *\fP\fIbuf\fP\fB);\fP
  60 .ad b
  61 .SH 説明
  62 \fBshmctl\fP()  は、識別子が \fIshmid\fP の System V 共有メモリ・セグメントに対して \fIcmd\fP
  63 で指示した制御命令を実行する。
  64 .PP
  65 \fIbuf\fP 引き数は、 \fIshmid_ds\fP 構造体へのポインタである。 この構造体は \fI<sys/shm.h>\fP
  66 で以下のように定義されている
  67 .PP
  68 .in +4n
  69 .nf
  70 struct shmid_ds {
  71     struct ipc_perm shm_perm;    /* 所有権と許可 */
  72     size_t          shm_segsz;   /* セグメントのサイズ (バイト) */
  73     time_t          shm_atime;   /* 最後の付加 (attach) の時刻 */
  74     time_t          shm_dtime;   /* 最後の分離 (detach) の時刻 */
  75     time_t          shm_ctime;   /* 最後に変更が行われた時刻 */
  76     pid_t           shm_cpid;    /* 作成者 (creator) の PID */
  77     pid_t           shm_lpid;    /* 最後の shmat(2)/shmdt(2) の PID */
  78     shmatt_t        shm_nattch;  /* 現在付加されている数 */
  79     ...
  80 };
  81 .fi
  82 .in
  83 .PP
  84 \fIipc_perm\fP 構造体は以下のように定義されている (強調されたフィールドは \fBIPC_SET\fP を使って設定可能である):
  85 .PP
  86 .in +4n
  87 .nf
  88 struct ipc_perm {
  89     key_t          __key;    /* shmget(2) に与えられるキー */
  90     uid_t          \fBuid\fP;      /* 所有者の実効 UID */
  91     gid_t          \fBgid\fP;      /* 所有者の実効 GID */
  92     uid_t          cuid;     /* 作成者の実効 UID */
  93     gid_t          cgid;     /* 作成者の実効 GID */
  94     unsigned short \fBmode\fP;     /* \fB許可\fP + SHM_DEST と
  95                                 SHM_LOCKED フラグ */
  96     unsigned short __seq;    /* シーケンス番号 */
  97 };
  98 .fi
  99 .in
 100 .PP
 101 \fIcmd\fP として有効な値は以下の通り:
 102 .br
 103 .TP  10
 104 \fBIPC_STAT\fP
 105 \fIshmid\fP に関連づけられたカーネルデータ構造体の情報を \fIbuf\fP で指された \fIshmid_ds\fP 構造体にコピーする。
 106 呼び出し元は共有メモリ・セグメントに対する 読み込み許可を持たなければならない。
 107 .TP
 108 \fBIPC_SET\fP
 109 \fIbuf\fP によって指される \fIshmid_ds\fP 構造体のいくつかのメンバーの値を、
 110 この共有メモリ・セグメントに関連づけられたカーネルデータ構造体に書き込み、 \fIshm_ctime\fP メンバーも更新する。
 111 以下のフィールドは変更できる。 \fIshm_perm.uid\fP, \fIshm_perm.gid\fP, \fIshm_perm.mode\fP (の最下位 9
 112 ビット)。 呼び出したプロセスの実効 UID が所有者 (\fIshm_perm.uid\fP)  または作成者 (\fIshm_perm.cuid\fP)
 113 と一致するか、呼び出し元が特権を持たなければならない。
 114 .TP
 115 \fBIPC_RMID\fP
 116 セグメントに破棄済みのマークを付ける。 セグメントは、実際には最後プロセスがセグメントを分離した (関連する \fIshmid_ds\fP 構造体の
 117 \fIshm_nattch\fP メンバーが 0 になった) 後でのみ破棄される。 呼び出し元は所有者か作成者であるか、特権を持たなければならない。
 118 セグメントに破棄のマークが付けられると、 関連するデータ構造体において \fIshm_perm.mode\fP フィールドの (標準ではない)
 119 \fBSHM_DEST\fP フラグが設定される。 このデータ構造体は \fBIPC_STAT\fP で取得される。
 120 .IP
 121 呼び出し元は最終的にはセグメントを忘れずに破棄\fIしなければならない\fP。 そうでなれば、フォールト (fault) されたページは メモリかスワップ
 122 (swap) に残り続ける。
 123 .IP
 124 \fBproc\fP(5) の \fI/proc/sys/kernel/shm_rmid_forced\fP の説明も参照のこと。
 125 .TP  10
 126 \fBIPC_INFO\fP (Linux 固有)
 127 システム全体での共有メモリの制限とパラメータに関する情報を、 \fIbuf\fP が指す構造体に入れて返す。 この構造体は \fIshminfo\fP 型である
 128 (そのためキャストが必要である)。 \fIshminfo\fP は \fB_GNU_SOURCE\fP 機能検査マクロが定義された場合に
 129 \fI<sys/shm.h>\fP で以下のように定義される:
 130 .nf
 131 .in +4n
 132
 133 struct  shminfo {
 134     unsigned long shmmax; /* 最大セグメントサイズ */
 135     unsigned long shmmin; /* 最小セグメントサイズ。
 136                              常に 1 */
 137     unsigned long shmmni; /* 最大セグメント数 */
 138     unsigned long shmseg; /* プロセスが付加できる
 139                              セグメントの最大数。
 140                              カーネル内では未使用 */
 141     unsigned long shmall; /* 共有メモリの最大ページ数。
 142                              システム全体での値 */
 143 };
 144
 145 .in
 146 .fi
 147 設定 \fIshmmni\fP, \fIshmmax\fP, \fIshmall\fP は \fI/proc\fP にある同じ名前のファイル経由で変更可能である。 詳しくは
 148 \fBproc\fP(5)  を参照。
 149 .TP
 150 \fBSHM_INFO\fP (Linux 固有)
 151 共有メモリが消費しているシステム資源に関する情報を 格納した \fIshm_info\fP 構造体を返す。 この構造体は、 \fB_GNU_SOURCE\fP
 152 機能検査マクロが定義された場合に \fI<sys/shm.h>\fP で以下のように定義される:
 153 .nf
 154 .in +4n
 155
 156 struct shm_info {
 157     int           used_ids; /* 現在存在するセグメント数 */
 158     unsigned long shm_tot;  /* 共有メモリのページ総数 */
 159     unsigned long shm_rss;  /* メモリ上にある (スワップされて
 160                                いない) 共有メモリページ数 */
 161     unsigned long shm_swp;  /* スワップされている共有メモリ
 162                                ページ数 */
 163     unsigned long swap_attempts;
 164                             /* Linux 2.4 以降では未使用 */
 165     unsigned long swap_successes;
 166                             /* Linux 2.4 以降では未使用 */
 167 };
 168 .in
 169 .fi
 170 .TP
 171 \fBSHM_STAT\fP (Linux 固有)
 172 \fBIPC_STAT\fP と同じく \fIshmid_ds\fP 構造体を返す。 但し、 \fIshmid\fP
 173 引き数は、セグメント識別子ではなく、システム上の全ての共有メモリ セグメントに関する情報を管理するカーネルの内部配列へのインデックス である。
 174 .PP
 175 呼び出し元は、\fIcmd\fP に以下の値を指定することで、共有メモリ・セグメントが スワップされることを防止したり、許可したりできる:
 176 .br
 177 .TP  10
 178 \fBSHM_LOCK\fP (Linux 固有)
 179 共有メモリ・セグメントをスワップすることを防止する。 ロックが有効になった後、呼び出し元は、
 180 存在することが要求された全てのページをフォールトさせなければならない。 セグメントがロックされると、 関連するデータ構造体において
 181 \fIshm_perm.mode\fP フィールドの (標準的ではない)  \fBSHM_LOCKED\fP フラグが設定される。 このデータ構造体は
 182 \fBIPC_STAT\fP で取得される。
 183 .TP
 184 \fBSHM_UNLOCK\fP (Linux 固有)
 185 セグメントのロックを解除し、スワップ・アウトすることを可能にする。
 186 .PP
 187 .\" There was some weirdness in 2.6.9: SHM_LOCK and SHM_UNLOCK could
 188 .\" be applied to a segment, regardless of ownership of the segment.
 189 .\" This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed
 190 .\" in 2.6.10.  MTK, May 2005
 191 2.6.10 より前のカーネルでは、特権プロセスだけが \fBSHM_LOCK\fP と \fBSHM_UNLOCK\fP を利用することができた。 2.6.10
 192 以降のカーネルでは、非特権プロセスであっても次の条件を満たせば これらの操作を利用することができる。その条件とは、プロセスの実効 UID
 193 がそのセグメントの所有者もしくは作成者の UID と一致し、 (\fBSHM_LOCK\fP の場合には) ロックするメモリの合計が
 194 \fBRLIMIT_MEMLOCK\fP リソース上限 (\fBsetrlimit\fP(2)  参照) の範囲内に入っていることである。
 195 .SH 返り値
 196 \fBIPC_INFO\fP と \fBSHM_INFO\fP 操作は、成功すると、全ての共有メモリセグメントに関する情報を
 197 管理しているカーネルの内部配列の使用中エントリのインデックスの うち最大値を返す (この情報は、システムの全ての共有メモリセグメントに関する情報を
 198 取得するために、 \fBSHM_STAT\fP 操作を繰り返し実行する際に使用できる)。 \fBSHM_STAT\fP 操作は、成功すると、 \fIshmid\fP
 199 で指定されたインデックスを持つ共有メモリセグメントの識別子を返す。 他の操作は、成功の場合 0 を返す。
 200
 201 エラーの場合は \-1 を返し、 \fIerrno\fP を適切に設定する。
 202 .SH エラー
 203 .TP
 204 \fBEACCES\fP
 205 \fBIPC_STAT\fP または \fBSHM_STAT\fP が要求され、 \fIshm_perm.mode\fP が \fIshmid\fP
 206 への読み込みアクセスを許しておらず、 かつ呼び出したプロセスが \fBCAP_IPC_OWNER\fP ケーパビリティ (capability)
 207 を持っていない。
 208 .TP
 209 \fBEFAULT\fP
 210 \fIcmd\fP 引き数に \fBIPC_SET\fP か \fBIPC_STAT\fP が指定されたが \fIbuf\fP で指されているアドレスにアクセスできない。
 211 .TP
 212 \fBEIDRM\fP
 213 \fIshmid\fP が削除 (remove) された識別子 (identifier) を指している。
 214 .TP
 215 \fBEINVAL\fP
 216 \fIshmid\fP が有効な識別子でないか、 \fIcmd\fP が有効なコマンドでない。 もしくは、 \fBSHM_STAT\fP 操作の場合に、 \fIshmid\fP
 217 で指定されたインデックス値が現在未使用の配列のスロットを参照していた。
 218 .TP
 219 \fBENOMEM\fP
 220 (2.6.9 以降のカーネルにおいて)  \fBSHM_LOCK\fP が指定され、 ロックされる予定のセグメントのサイズ
 221 (ロックされる共有メモリ・セグメントの合計バイト数) が、 呼び出したプロセスの実ユーザー ID についての制限を超えた。 この制限は
 222 \fBRLIMIT_MEMLOCK\fP ソフト資源制限で定義される (\fBsetrlimit\fP(2)  を参照)。
 223 .TP
 224 \fBEOVERFLOW\fP
 225 \fBIPC_STAT\fP が試みられ、GID や UID の値が \fIbuf\fP で指示される構造体に格納するには大き過ぎる。
 226 .TP
 227 \fBEPERM\fP
 228 \fBIPC_SET\fP か \fBIPC_RMID\fP が試みられ、 呼び出したプロセスの実効ユーザー ID が作成者 (\fIshm_perm.cuid\fP)
 229 でも所有者 (\fIshm_perm.uid\fP)  でもなく、プロセスが特権を持たない (Linux では \fBCAP_SYS_ADMIN\fP
 230 ケーパビリティを持たない)。
 231
 232 または (2.6.9 より前のカーネルで)  \fBSHM_LOCK\fP または \fBSHM_UNLOCK\fP が指定されているが、プロセスが特権を持たない
 233 (Linux では \fBCAP_IPC_LOCK\fP ケーパビリティを持たない)。 (Linux 2.6.9 以降では、
 234 \fBRLIMIT_MEMLOCK\fP が 0 で呼び出し元が特権を持たない場合にも、このエラーが起こる。)
 235 .SH 準拠
 236 .\" SVr4 documents additional error conditions EINVAL,
 237 .\" ENOENT, ENOSPC, ENOMEM, EEXIST.  Neither SVr4 nor SVID documents
 238 .\" an EIDRM error condition.
 239 SVr4, POSIX.1\-2001.
 240 .SH 注意
 241 .\" Like Linux, the FreeBSD man pages still document
 242 .\" the inclusion of these header files.
 243 Linux や POSIX の全てのバージョンでは、 \fI<sys/types.h>\fP と \fI<sys/ipc.h>\fP
 244 のインクルードは必要ない。しかしながら、いくつかの古い実装ではこれらのヘッダファイルのインクルードが必要であり、 SVID
 245 でもこれらのインクルードをするように記載されている。このような古いシステムへの移植性を意図したアプリケーションではこれらのファイルをインクルードする必要があるかもしれない。
 246
 247 \fBIPC_INFO\fP, \fBSHM_STAT\fP, \fBSHM_INFO\fP 操作は、 \fBipcs\fP(1)
 248 プログラムで割り当て済の資源に関する情報を提供するために 使用されている。将来、これらの操作は変更されたり、 /proc
 249 ファイルシステムのインタフェースに移動されるかもしれない。
 250
 251 Linux では、 \fIshmctl(IPC_RMID)\fP を使ってすでに削除マークがつけられている共有メモリ・セグメントを あるプロセスが付加
 252 (attach)  (\fBshmat\fP(2))  することを許可している。 この機能は他の UNIX の実装では利用できない。
 253 移植性を考慮したアプリケーションではこれに依存しないようにすべきである。
 254
 255 \fI構造体 shmid_ds\fP 内の多くのフィールドは、 Linux 2.2 では \fIshort\fP 型だったが、Linux 2.4 では
 256 \fIlong\fP 型になった。 この利点を生かすには、glibc\-2.1.91 以降の環境下で 再コンパイルすれば十分である。
 257 カーネルは新しい形式の呼び出しと古い形式の呼び出しを \fIcmd\fP 内の \fBIPC_64\fP フラグで区別する。
 258 .SH 関連項目
 259 \fBmlock\fP(2), \fBsetrlimit\fP(2), \fBshmget\fP(2), \fBshmop\fP(2), \fBcapabilities\fP(7),
 260 \fBshm_overview\fP(7), \fBsvipc\fP(7)
 261 .SH この文書について
 262 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.52 の一部
 263 である。プロジェクトの説明とバグ報告に関する情報は
 264 http://www.kernel.org/doc/man\-pages/ に書かれている。