| SHM_OPEN(3) | Linux Programmer's Manual | SHM_OPEN(3) |
名前¶
shm_open, shm_unlink - POSIX 共有メモリ・オブジェクトの作成/オープン/削除を行う
書式¶
#include <sys/mman.h>
#include <sys/stat.h> /* mode 定数用 */
#include <fcntl.h> /* O_*
定数の定義用 */
int shm_open(const char *name, int oflag, mode_t mode);
int shm_unlink(const char *name);
-lrt でリンクする。
説明¶
shm_open() は、POSIX 共有メモリ・オブジェクトを新規に作成/オープンしたり、 すでに存在するオブジェクトをオープンしたりする。 POSIX 共有メモリ・オブジェクトは、実際には、関係のないプロセスが 共有メモリの同じ領域を mmap(2) するために使用することができる手段である。 shm_unlink() は、逆の操作、つまり以前に shm_open() で作成されたオブジェクトの削除を行う。
shm_open() の動作は open(2) とよく似ている。 name で作成したりオープンしたりする共有メモリ・オブジェクトを指定する。 移植性を持たせるためには、共有メモリ・オブジェクトは /somename という形式の名前で識別し、 その名前は、最大で NAME_MAX (すなわち 255) 文字の NULL 終端された文字列で、 スラッシュで始まり、スラッシュ以外の文字が 1 文字以上続く形式 にすべきである。
oflag はビットマスクで、 O_RDONLY と O_RDWR のいずれか一方と、以下に述べる他のフラグの論理和をとったもの を指定する。
- O_RDONLY
- 読み出しアクセス用にオブジェクトをオープンする。 このフラグを指定してオープンされた共有メモリ・オブジェクトは、 読み出し (PROT_READ) アクセスでのみ mmap(2) することができる。
- O_RDWR
- 読み書きアクセス用にオブジェクトをオープンする。
- O_CREAT
- 存在しない場合、共有メモリ・オブジェクトを作成する。
オブジェクトのユーザとグループの所有権は、
呼び出し元プロセスの対応する実効
ID が使われ、
オブジェクトの許可ビットは
mode の下位 9
ビットに基づいて設定される。ただし、
ファイルモード作成マスク
(umask(2) 参照)
に設定されている値は、新規オブジェクトに関してはクリアされる。
mode
を定義するために使用できるマクロ定数(群)は
open(2)
に記載されている
(これらの定数のシンボル定義は
<sys/stat.h>
のインクルードにより得られる)。
新規に作成された共有メモリ・オブジェクトは長さ 0 で初期化される。 オブジェクトの大きさは ftruncate(2) を使って設定できる。 共有メモリ・オブジェクトとして新規に確保されたバイトは自動的に 0 に初期化される。
- O_EXCL
- O_CREAT が一緒に指定されており、 name で指定された共有メモリ・オブジェクトが既に存在した場合、 エラーを返す。 オブジェクトの存在確認と、存在しなかった場合のオブジェクト作成は、 必ず一連の操作として実行される (performed atomically)。
- O_TRUNC
- 共有メモリ・オブジェクトがすでに存在した場合、 そのオブジェクトを 0 バイトに切り詰める。
これらのフラグ値の定義は <fcntl.h> のインクルードにより得られる。
成功して完了した場合、 shm_open() は共有メモリ・オブジェクトを参照する新しいファイル・ディスクリプタを返す。 このファイル・ディスクリプタは、そのプロセス内で過去にオープンされていない ファイル・ディスクリプタの中で最も小さな数になることが保証される。 FD_CLOEXEC フラグ (fcntl(2) を参照) が、このファイル・ディスクリプタに設定される。
通常、これらのファイル・ディスクリプタは、この後続けて実行される ftruncate(2) (新規に作成されたオブジェクトの場合のみ) と mmap(2) の呼び出しに使用される。 mmap(2) を呼び出した後は、ファイル・ディスクリプタをクローズしてもよく、 クローズしてもメモリ・マッピングに影響を与えることはない。
shm_unlink() の動作は unlink(2) とよく似ている: 共有メモリ・オブジェクト名を削除し、すべてのプロセスが処理対象の オブジェクトをアンマップした時点でオブジェクトの割り当てを解除し、 対応するメモリ領域の内容を破棄する。 shm_unlink() が成功した後で、同じ name を持つオブジェクトに対して shm_open() を行うと、 (O_CREAT が指定されていない場合) 失敗する。 (O_CREAT が指定されている場合、新しく別のオブジェクトが作成される)。
返り値¶
成功した場合、 shm_open() は非負のファイル・ディスクリプタを返す。 失敗した場合、 shm_open() は -1 を返す。 shm_unlink() は、成功した場合 0 を、エラーが起こった場合 -1 を返す。
エラー¶
失敗した場合、エラーの原因を示すため errno が設定される。 errno に設定される値は以下の通りである:
- EACCES
- 共有メモリオブジェクトを shm_unlink() する権限がなかった。
- EACCES
- 指定された mode で name を shm_open() する権限がなかった。もしくは、 O_TRUNC が指定されたが、呼び出し元にはそのオブジェクトに対する書き込み権限が なかった。
- EEXIST
- O_CREAT と O_EXCL の両方が shm_open() に指定されたが、 name で指定された共有メモリ・オブジェクトが既に存在した。
- EINVAL
- shm_open() に与えられた name 引き数が不正であった。
- EMFILE
- プロセスがオープン可能なファイル数の上限にすでに達していた。
- ENAMETOOLONG
- name の長さが PATH_MAX を越えている。
- ENFILE
- ファイルシステムでオープンできるファイル数の上限に達した。
- ENOENT
- 存在していない name のオブジェクトを shm_open() しようとしたが、 O_CREAT が指定されていなかった。
- ENOENT
- 存在しない name のオブジェクトを shm_unlink() しようとした。
バージョン¶
これらの関数は glibc 2.2 以降で提供されている。
準拠¶
POSIX.1-2001.
POSIX.1-2001 には、新規に作成される共有メモリオブジェクトのグループ所有権は、 呼び出し元プロセスの実効グループ ID か 「システムのデフォルトのグループ ID」 のどちらかに設定される、と書かれている。
注意¶
POSIX は O_RDONLY と O_TRUNC が一緒に指定された場合の動作を未定義にしている。Linux では、 既存の共有メモリ・オブジェクトに対する切り詰め (truncate) は成功する。 しかし、他の UNIX システムでも同じであるとは限らない。
Linux 2.4 における POSIX 共有メモリ・オブジェクトの実装は 専用のファイルシステムを使用する。そのファイルシステムは通常 /dev/shm にマウントされる。
関連項目¶
close(2), fchmod(2), fchown(2), fcntl(2), fstat(2), ftruncate(2), mmap(2), open(2), umask(2), shm_overview(7)
この文書について¶
この man ページは Linux man-pages プロジェクトのリリース 3.51 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。
| 2009-02-25 | Linux |