.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright (C) 2002 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" FIXME . Add an example to this page
.\"
.\" Japanese Version Copyright (c) 2002 Akihiro MOTOKI, all rights reserved.
.\" Translated Mon Feb  2 2003 by Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
.\" Updated 2009-02-23, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.19
.\"
.TH SHM_OPEN 3 2009-02-25 "Linux" "Linux Programmer's Manual"
.\"O .SH NAME
.SH 名前
.\"O shm_open, shm_unlink \- Create/open or unlink POSIX shared memory objects
shm_open, shm_unlink \- POSIX 共有メモリ・オブジェクトの作成/オープン、
削除を行う
.\"O .SH SYNOPSIS
.SH 書式
.B #include <sys/mman.h>
.br
.\"O .BR "#include <sys/stat.h>" "        /* For mode constants */"
.BR "#include <sys/stat.h>" "        /* mode 定数用 */"
.br
.\"O .BR "#include <fcntl.h>" "           /* For O_* constants */"
.BR "#include <fcntl.h>" "           /* O_* 定数の定義用 */"
.sp
.BI "void * shm_open(const char *" name ", int " oflag ", mode_t " mode );
.sp
.BI "int shm_unlink(const char *" name );
.sp
.\"O Link with \fI\-lrt\fP.
\fI\-lrt\fP でリンクする。
.\"O .SH DESCRIPTION
.SH 説明
.\"O .BR shm_open ()
.\"O creates and opens a new, or opens an existing, POSIX shared memory object.
.\"O A POSIX shared memory object is in effect a handle which can
.\"O be used by unrelated processes to
.\"O .BR mmap (2)
.\"O the same region of shared memory.
.BR shm_open ()
は、POSIX 共有メモリ・オブジェクトを新規に作成/オープンしたり、
すでに存在するオブジェクトをオープンしたりする。
POSIX 共有メモリ・オブジェクトは、実際には、関係のないプロセスが
共有メモリの同じ領域を
.BR mmap (2)
するために使用することができる手段である。
.\"O The
.\"O .BR shm_unlink ()
.\"O function performs the converse operation,
.\"O removing an object previously created by
.\"O .BR shm_open ().
.BR shm_unlink ()
は、逆の操作、つまり以前に
.BR shm_open ()
で作成されたオブジェクトの削除を行う。
.LP
.\"O The operation of
.\"O .BR shm_open ()
.\"O is analogous to that of
.\"O .BR open (2).
.BR shm_open ()
の動作は
.BR open (2)
とよく似ている。
.\"O .I name
.\"O specifies the shared memory object to be created or opened.
.\"O For portable use,
.\"O a shared memory object should be identified by a name of the form
.\"O .IR /somename ;
.\"O that is, a null-terminated string of up to
.\"O .BI NAME_MAX
.\"O (i.e., 255) characters consisting of an initial slash,
.I name
で作成したりオープンしたりする共有メモリ・オブジェクトを指定する。
移植性を持たせるためには、共有メモリ・オブジェクトは
.I /somename
という形式の名前で識別し、
その名前は、最大で
.B NAME_MAX
(すなわち 255) 文字の NULL 終端された文字列で、
.\" glibc allows the initial slash to be omitted, and makes
.\" multiple initial slashes equivalent to a single slash.
.\" This differs from the implementation of POSIX message queues.
.\"O followed by one or more characters, none of which are slashes.
スラッシュで始まり、スラッシュ以外の文字が 1 文字以上続く形式
にすべきである。
.\" glibc allows subdirectory components in the name, in which
.\" case the subdirectory must exist under /dev/shm, and allow the
.\" required permissions if a user wants to create a shared memory
.\" object in that subdirectory.
.LP
.\"O .I oflag
.\"O is a bit mask created by ORing together exactly one of
.\"O .B O_RDONLY
.\"O or
.\"O .B O_RDWR
.\"O and any of the other flags listed here:
.I oflag
はビットマスクで、
.B O_RDONLY
と
.B O_RDWR
のいずれか一方と、以下に述べる他のフラグの論理和をとったもの
を指定する。
.TP 1.1i
.B O_RDONLY
.\"O Open the object for read access.
.\"O A shared memory object opened in this way can only be
.\"O .BR mmap (2)ed
.\"O for read (\fBPROT_READ\fP) access.
読み出しアクセス用にオブジェクトをオープンする。
このフラグを指定してオープンされた共有メモリ・オブジェクトは、
読み出し (\fBPROT_READ\fP) アクセスでのみ
.BR mmap (2)
することができる。
.TP
.B O_RDWR
.\"O Open the object for read-write access.
読み書きアクセス用にオブジェクトをオープンする。
.TP
.B O_CREAT
.\"O Create the shared memory object if it does not exist.
存在しない場合、共有メモリ・オブジェクトを作成する。
.\"O The user and group ownership of the object are taken
.\"O from the corresponding effective IDs of the calling process,
.\"O .\" In truth it is actually the file system IDs on Linux, but these
.\"O .\" are nearly always the same as the effective IDs.  (MTK, Jul 05)
.\"O and the object's
.\"O permission bits are set according to the low-order 9 bits of
.\"O .IR mode ,
.\"O except that those bits set in the process file mode
.\"O creation mask (see
.\"O .BR umask (2))
.\"O are cleared for the new object.
オブジェクトのユーザとグループの所有権は、
呼び出し元プロセスの対応する実効 ID が使われ、
.\" 本当は、Linux ではファイルシステム ID が使われるのだが、
.\" その値はほとんどいつも実効 ID と同じである。 (MTK, Jul 05)
オブジェクトの許可ビットは
.I mode
の下位 9 ビットに基づいて設定される。ただし、
ファイルモード作成マスク
.RB ( umask (2)
参照) に設定されている値は、新規オブジェクトに関してはクリアされる。
.\"O A set of macro constants which can be used to define
.\"O .I mode
.\"O is listed in
.\"O .BR open (2).
.\"O (Symbolic definitions of these constants can be obtained by including
.\"O .IR <sys/stat.h> .)
.I mode
を定義するために使用できるマクロ定数(群)は
.BR open (2)
に記載されている
(これらの定数のシンボル定義は
.I <sys/stat.h>
のインクルードにより得られる)。
.sp
.\"O A new shared memory object initially has zero length \(em the size of the
.\"O object can be set using
.\"O .BR ftruncate (2).
.\"O The newly-allocated bytes of a shared memory
.\"O object are automatically initialized to 0.
新規に作成された共有メモリ・オブジェクトは長さ 0 で初期化される。
オブジェクトの大きさは
.BR ftruncate (2)
を使って設定できる。
共有メモリ・オブジェクトとして新規に確保されたバイトは自動的に
0 に初期化される。
.TP
.B O_EXCL
.\"O If
.\"O .B O_CREAT
.\"O was also specified, and a shared memory object with the given
.\"O .I name
.\"O already exists, return an error.
.\"O The check for the existence of the object, and its creation if it
.\"O does not exist, are performed atomically.
.B O_CREAT
が一緒に指定されており、
.I name
で指定された共有メモリ・オブジェクトが既に存在した場合、
エラーを返す。
オブジェクトの存在確認と、存在しなかった場合のオブジェクト作成は、
必ず一連の操作として実行される (performed atomically)。
.TP
.B O_TRUNC
.\"O If the shared memory object already exists, truncate it to zero bytes.
共有メモリ・オブジェクトがすでに存在した場合、
そのオブジェクトを 0 バイトに切り詰める。
.LP
.\"O Definitions of these flag values can be obtained by including
.\"O .IR <fcntl.h> .
これらのフラグ値の定義は
.I <fcntl.h>
のインクルードにより得られる。
.LP
.\"O On successful completion
.\"O .BR shm_open ()
.\"O returns a new file descriptor referring to the shared memory object.
.\"O This file descriptor is guaranteed to be the lowest-numbered file descriptor
.\"O not previously opened within the process.
.\"O The
.\"O .B FD_CLOEXEC
.\"O flag (see
.\"O .BR fcntl (2))
.\"O is set for the file descriptor.
成功して完了した場合、
.BR shm_open ()
は共有メモリ・オブジェクトを参照する新しいファイル・ディスクリプタを返す。
このファイル・ディスクリプタは、そのプロセス内で過去にオープンされていない
ファイル・ディスクリプタの中で最も小さな数になることが保証される。
.B FD_CLOEXEC
フラグ
.RB ( fcntl (2)
を参照) が、このファイル・ディスクリプタに設定される。
.PP
.\"O The file descriptor is normally used in subsequent calls
.\"O to
.\"O .BR ftruncate (2)
.\"O (for a newly created object) and
.\"O .BR mmap (2).
.\"O After a call to
.\"O .BR mmap (2)
.\"O the file descriptor may be closed without affecting the memory mapping.
通常、これらのファイル・ディスクリプタは、この後続けて実行される
.BR ftruncate (2)
(新規に作成されたオブジェクトの場合のみ) と
.BR mmap (2)
の呼び出しに使用される。
.BR mmap (2)
を呼び出した後は、ファイル・ディスクリプタをクローズしてもよく、
クローズしてもメモリ・マッピングに影響を与えることはない。
.PP
.\"O The operation
.\"O of
.\"O .BR shm_unlink ()
.\"O is analogous to
.\"O .BR unlink (2):
.\"O it removes a shared memory object name, and, once all processes
.\"O have unmapped the object, de-allocates and
.\"O destroys the contents of the associated memory region.
.BR shm_unlink ()
の動作は
.BR unlink (2)
とよく似ている:
共有メモリ・オブジェクト名を削除し、すべてのプロセスが処理対象の
オブジェクトをアンマップした時点でオブジェクトの割り当てを解除し、
対応するメモリ領域の内容を破棄する。
.\"O After a successful
.\"O .BR shm_unlink (),
.\"O attempts to
.\"O .BR shm_open ()
.\"O an object with the same
.\"O .I name
.\"O will fail (unless
.\"O .B O_CREAT
.\"O was specified, in which case a new, distinct object is created).
.BR shm_unlink ()
が成功した後で、同じ
.I name
を持つオブジェクトに対して
.BR shm_open ()
を行うと、
.RB ( O_CREAT
が指定されていない場合) 失敗する。
.RB ( O_CREAT
が指定されている場合、新しく別のオブジェクトが作成される)。
.\"O .SH "RETURN VALUE"
.SH 返り値
.\"O On success,
.\"O .BR shm_open ()
.\"O returns a nonnegative file descriptor.
.\"O On failure,
.\"O .B shm_open ()
.\"O returns \-1.
.\"O .BR shm_unlink ()
.\"O returns 0 on success, or \-1 on error.
成功した場合、
.BR shm_open ()
は非負のファイル・ディスクリプタを返す。
失敗した場合、
.BR shm_open ()
は \-1 を返す。
.BR shm_unlink ()
は、成功した場合 0 を、エラーが起こった場合 \-1 を返す。
.\"O .SH ERRORS
.SH エラー
.\"O On failure,
.\"O .I errno
.\"O is set to indicate the cause of the error.
.\"O Values which may appear in
.\"O .I errno
.\"O include the following:
失敗した場合、エラーの原因を示すため
.I errno
が設定される。
.I errno
に設定される値は以下の通りである:
.TP
.B EACCES
.\"O Permission to
.\"O .BR shm_unlink ()
.\"O the shared memory object was denied.
共有メモリオブジェクトを
.BR shm_unlink ()
する権限がなかった。
.TP
.B EACCES
.\"O Permission was denied to
.\"O .BR shm_open ()
.\"O .I name
.\"O in the specified
.\"O .IR mode ,
.\"O or
.\"O .B O_TRUNC
.\"O was specified and the caller does not have write permission on the object.
指定された
.I mode
で
.I name
を
.BR shm_open ()
する権限がなかった。もしくは、
.B O_TRUNC
が指定されたが、呼び出し元にはそのオブジェクトに対する書き込み権限が
なかった。
.TP
.B EEXIST
.\"O Both
.\"O .B O_CREAT
.\"O and
.\"O .B O_EXCL
.\"O were specified to
.\"O .BR shm_open ()
.\"O and the shared memory object specified by
.\"O .I name
.\"O already exists.
.B O_CREAT
と
.B O_EXCL
の両方が
.BR shm_open ()
に指定されたが、
.I name
で指定された共有メモリ・オブジェクトが既に存在した。
.TP
.B EINVAL
.\"O The
.\"O .I name
.\"O argument to
.\"O .BR shm_open ()
.\"O was invalid.
.BR shm_open ()
に与えられた
.I name
引き数が不正であった。
.TP
.B EMFILE
.\"O The process already has the maximum number of files open.
プロセスがオープン可能なファイル数の上限にすでに達していた。
.TP
.B ENAMETOOLONG
.\"O The length of
.\"O .I name
.\"O exceeds
.\"O .BR PATH_MAX .
.I name
の長さが
.B PATH_MAX
を越えている。
.TP
.B ENFILE
.\"O The limit on the total number of files open on the system has been
.\"O reached.
ファイルシステムでオープンできるファイル数の上限に達した。
.TP
.B ENOENT
.\"O An attempt was made to
.\"O .BR shm_open ()
.\"O a
.\"O .I name
.\"O that did not exist, and
.\"O .B O_CREAT
.\"O was not specified.
存在していない
.I name
のオブジェクトを
.BR shm_open ()
しようとしたが、
.B O_CREAT
が指定されていなかった。
.TP
.B ENOENT
.\"O An attempt was to made to
.\"O .BR shm_unlink ()
.\"O a
.\"O .I name
.\"O that does not exist.
存在しない
.I name
のオブジェクトを
.BR shm_unlink ()
しようとした。
.\"O .SH VERSIONS
.SH バージョン
.\"O These functions are provided in glibc 2.2 and later.
これらの関数は glibc 2.2 以降で提供されている。
.\"O .SH "CONFORMING TO"
.SH 準拠
POSIX.1-2001.
.LP
.\"O POSIX.1-2001 says that the group ownership of a newly created shared
.\"O memory object is set to either the calling process's effective group ID
.\"O or "a system default group ID".
POSIX.1-2001 には、新規に作成される共有メモリオブジェクトのグループ所有権は、
呼び出し元プロセスの実効グループ ID か 「システムのデフォルトのグループ ID」
のどちらかに設定される、と書かれている。
.\"O .SH "NOTES"
.SH 注意
.LP
.\"O POSIX leaves the behavior of the combination of
.\"O .B O_RDONLY
.\"O and
.\"O .B O_TRUNC
.\"O unspecified.
.\"O On Linux, this will successfully truncate an existing
.\"O shared memory object \(em this may not be so on other UNIX systems.
POSIX は
.B O_RDONLY
と
.B O_TRUNC
が一緒に指定された場合の動作を未定義にしている。Linux では、
既存の共有メモリ・オブジェクトに対する切り詰め (truncate) は成功する。
しかし、他の UNIX システムでも同じであるとは限らない。
.LP
.\"O The POSIX shared memory object implementation on Linux 2.4 makes use
.\"O of a dedicated file system, which is normally
.\"O mounted under
.\"O .IR /dev/shm .
Linux 2.4 における POSIX 共有メモリ・オブジェクトの実装は
専用のファイルシステムを使用する。そのファイルシステムは通常
.I /dev/shm
にマウントされる。
.\"O .SH "SEE ALSO"
.SH 関連項目
.BR close (2),
.BR fchmod (2),
.BR fchown (2),
.BR fcntl (2),
.BR fstat (2),
.BR ftruncate (2),
.BR mmap (2),
.BR open (2),
.BR umask (2),
.BR shm_overview (7)