リナックスコマンド

shm_openのヘルプ・マニュアル

日本語 英語

• help
• man

shm_open --help

man shm_open

SHM_OPEN(3) Linux Programmer’s Manual SHM_OPEN(3) 名前 shm_open, shm_unlink - POSIX 共有メモリ・オブジェクトの作成/オープン、 削除を行う 書式 #include #include /* mode 定数用 */ #include /* O_* 定数の定義用 */ void * 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) に記載されている (これらの定数のシンボル 定 義は のインクルードにより得られる)。 新 規に作成された共有メモリ・オブジェクトは長さ 0 で初期化さ れる。オブジェクトの大きさは ftruncate(2) を使って設定できる 。共有メモリ・オブジェクトとして新規に確保されたバイトは自動 的に 0 に初期化される。 O_EXCL O_CREAT が一緒に指定されており、 name で指定された共有メモリ ・オブジェクトが既に存在した場合、エラーを返す。オブジェクト の存在確認と、存在しなかった場合のオブジェクト作成は、必ず一 連の操作として実行される (performed atomically)。 O_TRUNC 共有メモリ・オブジェクトがすでに存在した場合、そのオブジェク トを 0 バイトに切り詰める。 これらのフラグ値の定義は のインクルードにより得られる。 成功して完了した場合、 shm_open() は共有メモリ・オブジェクトを参照す る 新 しいファイル・ディスクリプタを返す。このファイル・ディスクリプタは、 そのプロセス内で過去にオープンされていないファイル・ディスクリプタの 中 で最も小さな数になることが保証される。 FD_CLOEXEC フラグ (fcntl(2) を参 照) が、このファイル・ディスクリプタに設定される。 通常、これらのファイル・ディスクリプタは、この後続けて実行される ftrun- cate(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 では、既存の共有メモリ・オブジェクトに対する切り詰め (trun- cate) は成功する。しかし、他の 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) Linux 2009-02-25 SHM_OPEN(3)

SHM_OPEN(3) Linux Programmer’s Manual SHM_OPEN(3) NAME shm_open, shm_unlink - Create/open or unlink POSIX shared memory objects SYNOPSIS #include #include /* For mode constants */ #include /* For O_* constants */ int shm_open(const char *name, int oflag, mode_t mode); int shm_unlink(const char *name); Link with -lrt. DESCRIPTION shm_open() creates and opens a new, or opens an existing, POSIX shared memory object. A POSIX shared memory object is in effect a handle which can be used by unrelated processes to mmap(2) the same region of shared memory. The shm_unlink() function performs the converse opera- tion, removing an object previously created by shm_open(). The operation of shm_open() is analogous to that of open(2). name specifies the shared memory object to be created or opened. For portable use, a shared memory object should be identified by a name of the form /somename; that is, a null-terminated string of up to NAME_MAX (i.e., 255) characters consisting of an initial slash, followed by one or more characters, none of which are slashes. oflag is a bit mask created by ORing together exactly one of O_RDONLY or O_RDWR and any of the other flags listed here: O_RDONLY Open the object for read access. A shared memory object opened in this way can only be mmap(2)ed for read (PROT_READ) access. O_RDWR Open the object for read-write access. O_CREAT Create the shared memory object if it does not exist. The user and group ownership of the object are taken from the corresponding effective IDs of the calling process, and the object’s permission bits are set according to the low-order 9 bits of mode, except that those bits set in the process file mode creation mask (see umask(2)) are cleared for the new object. A set of macro constants which can be used to define mode is listed in open(2). (Symbolic definitions of these constants can be obtained by including .) A new shared memory object initially has zero length — the size of the object can be set using ftruncate(2). The newly allocated bytes of a shared memory object are automatically initialized to 0. O_EXCL If O_CREAT was also specified, and a shared memory object with the given name already exists, return an error. The check for the existence of the object, and its creation if it does not exist, are performed atomically. O_TRUNC If the shared memory object already exists, truncate it to zero bytes. Definitions of these flag values can be obtained by including . On successful completion shm_open() returns a new file descriptor referring to the shared memory object. This file descriptor is guaran- teed to be the lowest-numbered file descriptor not previously opened within the process. The FD_CLOEXEC flag (see fcntl(2)) is set for the file descriptor. The file descriptor is normally used in subsequent calls to ftrun- cate(2) (for a newly created object) and mmap(2). After a call to mmap(2) the file descriptor may be closed without affecting the memory mapping. The operation of shm_unlink() is analogous to unlink(2): it removes a shared memory object name, and, once all processes have unmapped the object, de-allocates and destroys the contents of the associated memory region. After a successful shm_unlink(), attempts to shm_open() an object with the same name will fail (unless O_CREAT was specified, in which case a new, distinct object is created). RETURN VALUE On success, shm_open() returns a non-negative file descriptor. On failure, shm_open() returns -1. shm_unlink() returns 0 on success, or -1 on error. ERRORS On failure, errno is set to indicate the cause of the error. Values which may appear in errno include the following: EACCES Permission to shm_unlink() the shared memory object was denied. EACCES Permission was denied to shm_open() name in the specified mode, or O_TRUNC was specified and the caller does not have write per- mission on the object. EEXIST Both O_CREAT and O_EXCL were specified to shm_open() and the shared memory object specified by name already exists. EINVAL The name argument to shm_open() was invalid. EMFILE The process already has the maximum number of files open. ENAMETOOLONG The length of name exceeds PATH_MAX. ENFILE The limit on the total number of files open on the system has been reached. ENOENT An attempt was made to shm_open() a name that did not exist, and O_CREAT was not specified. ENOENT An attempt was to made to shm_unlink() a name that does not exist. VERSIONS These functions are provided in glibc 2.2 and later. CONFORMING TO POSIX.1-2001. POSIX.1-2001 says that the group ownership of a newly created shared memory object is set to either the calling process’s effective group ID or "a system default group ID". NOTES POSIX leaves the behavior of the combination of O_RDONLY and O_TRUNC unspecified. On Linux, this will successfully truncate an existing shared memory object — this may not be so on other Unix systems. The POSIX shared memory object implementation on Linux 2.4 makes use of a dedicated file system, which is normally mounted under /dev/shm. SEE ALSO close(2), fchmod(2), fchown(2), fcntl(2), fstat(2), ftruncate(2), mmap(2), open(2), umask(2), shm_overview(7) COLOPHON This page is part of release 3.22 of the Linux man-pages project. A description of the project, and information about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/. Linux 2009-02-25 SHM_OPEN(3)