release/man3/shm_open.3

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (C) 2002 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\"
  25 .\" FIXME . Add an example to this page
  26 .\"
  27 .\" Japanese Version Copyright (c) 2002 Akihiro MOTOKI, all rights reserved.
  28 .\" Translated Mon Feb  2 2003 by Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  29 .\" Updated 2009-02-23, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.19
  30 .\"
  31 .TH SHM_OPEN 3 2009-02-25 "Linux" "Linux Programmer's Manual"
  32 .SH 名前
  33 shm_open, shm_unlink \- POSIX 共有メモリ・オブジェクトの作成/オープン、
  34 削除を行う
  35 .SH 書式
  36 .B #include <sys/mman.h>
  37 .br
  38 .BR "#include <sys/stat.h>" "        /* mode 定数用 */"
  39 .br
  40 .BR "#include <fcntl.h>" "           /* O_* 定数の定義用 */"
  41 .sp
  42 .BI "void * shm_open(const char *" name ", int " oflag ", mode_t " mode );
  43 .sp
  44 .BI "int shm_unlink(const char *" name );
  45 .sp
  46 \fI\-lrt\fP でリンクする。
  47 .SH 説明
  48 .BR shm_open ()
  49 は、POSIX 共有メモリ・オブジェクトを新規に作成/オープンしたり、
  50 すでに存在するオブジェクトをオープンしたりする。
  51 POSIX 共有メモリ・オブジェクトは、実際には、関係のないプロセスが
  52 共有メモリの同じ領域を
  53 .BR mmap (2)
  54 するために使用することができる手段である。
  55 .BR shm_unlink ()
  56 は、逆の操作、つまり以前に
  57 .BR shm_open ()
  58 で作成されたオブジェクトの削除を行う。
  59 .LP
  60 .BR shm_open ()
  61 の動作は
  62 .BR open (2)
  63 とよく似ている。
  64 .I name
  65 で作成したりオープンしたりする共有メモリ・オブジェクトを指定する。
  66 移植性を持たせるためには、共有メモリ・オブジェクトは
  67 .I /somename
  68 という形式の名前で識別し、
  69 その名前は、最大で
  70 .B NAME_MAX
  71 (すなわち 255) 文字の NULL 終端された文字列で、
  72 .\" glibc allows the initial slash to be omitted, and makes
  73 .\" multiple initial slashes equivalent to a single slash.
  74 .\" This differs from the implementation of POSIX message queues.
  75 スラッシュで始まり、スラッシュ以外の文字が 1 文字以上続く形式
  76 にすべきである。
  77 .\" glibc allows subdirectory components in the name, in which
  78 .\" case the subdirectory must exist under /dev/shm, and allow the
  79 .\" required permissions if a user wants to create a shared memory
  80 .\" object in that subdirectory.
  81 .LP
  82 .I oflag
  83 はビットマスクで、
  84 .B O_RDONLY
  85 と
  86 .B O_RDWR
  87 のいずれか一方と、以下に述べる他のフラグの論理和をとったもの
  88 を指定する。
  89 .TP 1.1i
  90 .B O_RDONLY
  91 読み出しアクセス用にオブジェクトをオープンする。
  92 このフラグを指定してオープンされた共有メモリ・オブジェクトは、
  93 読み出し (\fBPROT_READ\fP) アクセスでのみ
  94 .BR mmap (2)
  95 することができる。
  96 .TP
  97 .B O_RDWR
  98 読み書きアクセス用にオブジェクトをオープンする。
  99 .TP
 100 .B O_CREAT
 101 存在しない場合、共有メモリ・オブジェクトを作成する。
 102 オブジェクトのユーザとグループの所有権は、
 103 呼び出し元プロセスの対応する実効 ID が使われ、
 104 .\" 本当は、Linux ではファイルシステム ID が使われるのだが、
 105 .\" その値はほとんどいつも実効 ID と同じである。 (MTK, Jul 05)
 106 オブジェクトの許可ビットは
 107 .I mode
 108 の下位 9 ビットに基づいて設定される。ただし、
 109 ファイルモード作成マスク
 110 .RB ( umask (2)
 111 参照) に設定されている値は、新規オブジェクトに関してはクリアされる。
 112 .I mode
 113 を定義するために使用できるマクロ定数(群)は
 114 .BR open (2)
 115 に記載されている
 116 (これらの定数のシンボル定義は
 117 .I <sys/stat.h>
 118 のインクルードにより得られる)。
 119 .sp
 120 新規に作成された共有メモリ・オブジェクトは長さ 0 で初期化される。
 121 オブジェクトの大きさは
 122 .BR ftruncate (2)
 123 を使って設定できる。
 124 共有メモリ・オブジェクトとして新規に確保されたバイトは自動的に
 125 0 に初期化される。
 126 .TP
 127 .B O_EXCL
 128 .B O_CREAT
 129 が一緒に指定されており、
 130 .I name
 131 で指定された共有メモリ・オブジェクトが既に存在した場合、
 132 エラーを返す。
 133 オブジェクトの存在確認と、存在しなかった場合のオブジェクト作成は、
 134 必ず一連の操作として実行される (performed atomically)。
 135 .TP
 136 .B O_TRUNC
 137 共有メモリ・オブジェクトがすでに存在した場合、
 138 そのオブジェクトを 0 バイトに切り詰める。
 139 .LP
 140 これらのフラグ値の定義は
 141 .I <fcntl.h>
 142 のインクルードにより得られる。
 143 .LP
 144 成功して完了した場合、
 145 .BR shm_open ()
 146 は共有メモリ・オブジェクトを参照する新しいファイル・ディスクリプタを返す。
 147 このファイル・ディスクリプタは、そのプロセス内で過去にオープンされていない
 148 ファイル・ディスクリプタの中で最も小さな数になることが保証される。
 149 .B FD_CLOEXEC
 150 フラグ
 151 .RB ( fcntl (2)
 152 を参照) が、このファイル・ディスクリプタに設定される。
 153 .PP
 154 通常、これらのファイル・ディスクリプタは、この後続けて実行される
 155 .BR ftruncate (2)
 156 (新規に作成されたオブジェクトの場合のみ) と
 157 .BR mmap (2)
 158 の呼び出しに使用される。
 159 .BR mmap (2)
 160 を呼び出した後は、ファイル・ディスクリプタをクローズしてもよく、
 161 クローズしてもメモリ・マッピングに影響を与えることはない。
 162 .PP
 163 .BR shm_unlink ()
 164 の動作は
 165 .BR unlink (2)
 166 とよく似ている:
 167 共有メモリ・オブジェクト名を削除し、すべてのプロセスが処理対象の
 168 オブジェクトをアンマップした時点でオブジェクトの割り当てを解除し、
 169 対応するメモリ領域の内容を破棄する。
 170 .BR shm_unlink ()
 171 が成功した後で、同じ
 172 .I name
 173 を持つオブジェクトに対して
 174 .BR shm_open ()
 175 を行うと、
 176 .RB ( O_CREAT
 177 が指定されていない場合) 失敗する。
 178 .RB ( O_CREAT
 179 が指定されている場合、新しく別のオブジェクトが作成される)。
 180 .SH 返り値
 181 成功した場合、
 182 .BR shm_open ()
 183 は非負のファイル・ディスクリプタを返す。
 184 失敗した場合、
 185 .BR shm_open ()
 186 は \-1 を返す。
 187 .BR shm_unlink ()
 188 は、成功した場合 0 を、エラーが起こった場合 \-1 を返す。
 189 .SH エラー
 190 失敗した場合、エラーの原因を示すため
 191 .I errno
 192 が設定される。
 193 .I errno
 194 に設定される値は以下の通りである:
 195 .TP
 196 .B EACCES
 197 共有メモリオブジェクトを
 198 .BR shm_unlink ()
 199 する権限がなかった。
 200 .TP
 201 .B EACCES
 202 指定された
 203 .I mode
 204 で
 205 .I name
 206 を
 207 .BR shm_open ()
 208 する権限がなかった。もしくは、
 209 .B O_TRUNC
 210 が指定されたが、呼び出し元にはそのオブジェクトに対する書き込み権限が
 211 なかった。
 212 .TP
 213 .B EEXIST
 214 .B O_CREAT
 215 と
 216 .B O_EXCL
 217 の両方が
 218 .BR shm_open ()
 219 に指定されたが、
 220 .I name
 221 で指定された共有メモリ・オブジェクトが既に存在した。
 222 .TP
 223 .B EINVAL
 224 .BR shm_open ()
 225 に与えられた
 226 .I name
 227 引き数が不正であった。
 228 .TP
 229 .B EMFILE
 230 プロセスがオープン可能なファイル数の上限にすでに達していた。
 231 .TP
 232 .B ENAMETOOLONG
 233 .I name
 234 の長さが
 235 .B PATH_MAX
 236 を越えている。
 237 .TP
 238 .B ENFILE
 239 ファイルシステムでオープンできるファイル数の上限に達した。
 240 .TP
 241 .B ENOENT
 242 存在していない
 243 .I name
 244 のオブジェクトを
 245 .BR shm_open ()
 246 しようとしたが、
 247 .B O_CREAT
 248 が指定されていなかった。
 249 .TP
 250 .B ENOENT
 251 存在しない
 252 .I name
 253 のオブジェクトを
 254 .BR shm_unlink ()
 255 しようとした。
 256 .SH バージョン
 257 これらの関数は glibc 2.2 以降で提供されている。
 258 .SH 準拠
 259 POSIX.1-2001.
 260 .LP
 261 POSIX.1-2001 には、新規に作成される共有メモリオブジェクトのグループ所有権は、
 262 呼び出し元プロセスの実効グループ ID か 「システムのデフォルトのグループ ID」
 263 のどちらかに設定される、と書かれている。
 264 .SH 注意
 265 .LP
 266 POSIX は
 267 .B O_RDONLY
 268 と
 269 .B O_TRUNC
 270 が一緒に指定された場合の動作を未定義にしている。Linux では、
 271 既存の共有メモリ・オブジェクトに対する切り詰め (truncate) は成功する。
 272 しかし、他の UNIX システムでも同じであるとは限らない。
 273 .LP
 274 Linux 2.4 における POSIX 共有メモリ・オブジェクトの実装は
 275 専用のファイルシステムを使用する。そのファイルシステムは通常
 276 .I /dev/shm
 277 にマウントされる。
 278 .SH 関連項目
 279 .BR close (2),
 280 .BR fchmod (2),
 281 .BR fchown (2),
 282 .BR fcntl (2),
 283 .BR fstat (2),
 284 .BR ftruncate (2),
 285 .BR mmap (2),
 286 .BR open (2),
 287 .BR umask (2),
 288 .BR shm_overview (7)