shmctlのヘルプ・マニュアル
日本語 英語
shmctl --help
man shmctl
SHMCTL(2) Linux Programmer’s Manual SHMCTL(2)
名前
shmctl - 共有メモリ (shared memory) を制御する
書式
#include
#include
int shmctl(int shmid, int cmd, struct shmid_ds *buf);
説明
shmctl() は、識別子が shmid の共有メモリ・セグメントに対して cmd で指示
した制御命令を実行する。
buf 引き数は、 shmid_ds 構造体へのポインタで あ る 。 こ の 構 造 体 は
で以下のように定義されている
struct shmid_ds {
struct ipc_perm shm_perm; /* 所有権と許可 */
size_t shm_segsz; /* セグメントのサイズ (バイト) */
time_t shm_atime; /* 最後の付加 (attach) の時刻 */
time_t shm_dtime; /* 最後の分離 (detach) の時刻 */
time_t shm_ctime; /* 最後に変更が行われた時刻 */
pid_t shm_cpid; /* 作成者 (creator) の PID */
pid_t shm_lpid; /* 最後の shmat(2)/shmdt(2) の PID */
shmatt_t shm_nattch; /* 現在付加されている数 */
...
};
ipc_perm 構造体は で以下のように定義されている (強調された
フィールドは IPC_SET を使って設定可能である):
struct ipc_perm {
key_t __key; /* shmget(2) に与えられるキー */
uid_t uid; /* 所有者の実効 UID */
gid_t gid; /* 所有者の実効 GID */
uid_t cuid; /* 作成者の実効 UID */
gid_t cgid; /* 作成者の実効 GID */
unsigned short mode; /* 許可 + SHM_DEST と
SHM_LOCKED フラグ */
unsigned short __seq; /* シーケンス番号 */
};
cmd として有効な値は以下の通り:
IPC_STAT shmid に関連づけられたカーネルデータ構造体の情報を buf で指さ
れ た shmid_ds 構造体にコピーする。呼び出し元は共有メモリ・セ
グメントに対する読み込み許可を持たなければならない。
IPC_SET buf によって指される shmid_ds 構造体のいくつかのメンバーの 値
を 、この共有メモリ・セグメントに関連づけられたカーネルデータ
構造体に書き込み、 shm_ctime メンバーも更新する。以下のフィー
ル ドは変更できる。 shm_perm.uid, shm_perm.gid, shm_perm.mode
(の最下位 9 ビット)。呼び出したプロセスの実効 UID が 所 有 者
(shm_perm.uid) または作成者 (shm_perm.cuid) と一致するか、呼
び出し元が特権を持たなければならない。
IPC_RMID セグメントに破棄済みのマークを付ける。セグメントは、実際に は
最 後プロセスがセグメントを分離した (関連する shmid_ds 構造体
の shm_nattch メンバーが 0 になった) 後でのみ破棄される。呼び
出 し元は所有者か作成者であるか、特権を持たなければならない。
セグメントに破棄のマークが付けられると、関連するデータ構造 体
に お いて shm_perm.mode フィールドの (標準ではない) SHM_DEST
フラグが設定される。このデータ構造体は IPC_STAT で取得され る
。
呼 び出し元は最終的にはセグメントを忘れずに破棄しなければならない。そう
でなれば、フォールト (fault) されたページはメモリかスワップ (swap) に残
り続ける。
IPC_INFO (Linux 固有)
シ ステム全体での共有メモリの制限とパラメータに関する情報を、
buf が指す構造体に入れて返す。この構造体は shminfo 型である (
そのためキャストが必要である)。 shminfo は _GNU_SOURCE 機能検
査マクロが定義された場合に で以下のように定義され
る:
struct shminfo {
unsigned long shmmax; /* 最大セグメントサイズ */
unsigned long shmmin; /* 最小セグメントサイズ。
常に 1 */
unsigned long shmmni; /* 最大セグメント数 */
unsigned long shmseg; /* プロセスが付加できる
セグメントの最大数。
カーネル内では未使用 */
unsigned long shmall; /* 共有メモリの最大ページ数。
システム全体での値 */
};
設定 shmmni, shmmax, shmall は /proc にある同じ名前のファイル
経由で変更可能である。詳しくは proc(5) を参照。
SHM_INFO (Linux 固有)
共有メモリが消費しているシステム資源に関する情報を格 納 し た
shm_info 構造体を返す。この構造体は、 _GNU_SOURCE 機能検査マ
クロが定義された場合に で以下のように定義される:
struct shm_info {
int used_ids; /* 現在存在するセグメント数 */
unsigned long shm_tot; /* 共有メモリのページ総数 */
unsigned long shm_rss; /* メモリ上にある (スワップされて
いない) 共有メモリページ数 */
unsigned long shm_swp; /* スワップされている共有メモリ
ページ数 */
unsigned long swap_attempts;
/* Linux 2.4 以降では未使用 */
unsigned long swap_successes;
/* Linux 2.4 以降では未使用 */
};
SHM_STAT (Linux 固有)
IPC_STAT と同じく shmid_ds 構造体を返す。但し、 shmid 引き 数
は 、セグメント識別子ではなく、システム上の全ての共有メモリセ
グメントに関する情報を管理するカーネルの内部配列へのインデ ッ
クスである。
呼 び出し元は、cmd に以下の値を指定することで、共有メモリ・セグメントが
スワップされることを防止したり、許可したりできる:
SHM_LOCK (Linux 固有)
共有メモリ・セグメントをスワップすることを防止する。ロック が
有 効になった後、呼び出し元は、存在することが要求された全ての
ページをフォールトさせなければならない。セグメントがロック さ
れると、関連するデータ構造体において shm_perm.mode フィールド
の (標準的ではない) SHM_LOCKED フラグが設定される。このデータ
構造体は IPC_STAT で取得される。
SHM_UNLOCK (Linux 固有)
セ グメントのロックを解除し、スワップ・アウトすることを可能に
する。
2.6.10 より前のカーネルでは、特権プロセスだけが SHM_LOCK と SHM_UNLOCK
を 利用することができた。 2.6.10 以降のカーネルでは、非特権プロセスであ
っても次の条件を満たせばこれらの操作を利用することができる。その条件 と
は 、プロセスの実効 UID がそのセグメントの所有者もしくは作成者の UID と
一致し、 (SHM_LOCK の場合には) ロックするメモリの合計が RLIMIT_MEMLOCK
リソース上限 (setrlimit(2) 参照) の範囲内に入っていることである。
返り値
IPC_INFO と SHM_INFO 操作は、成功すると、全ての共有メモリセグメントに関
する情報を管理しているカーネルの内部配列の使用中エントリのインデック ス
の うち最大値を返す (この情報は、システムの全ての共有メモリセグメントに
関する情報を取得するために、 SHM_STAT 操作を繰り返し実行する際に使用 で
き る)。 SHM_STAT 操作は、成功すると、 shmid で指定されたインデックスを
持つ共有メモリセグメントの識別子を返す。他の操作は、成功の場合 0 を返す
。
エラーの場合は -1 を返し、 errno を適切に設定する。
エラー
EACCES IPC_STAT または SHM_STAT が要求され、 shm_perm.mode が shmid へ
の読み込みアクセスを許しておらず、かつ呼び出し た プ ロ セ ス が
CAP_IPC_OWNER ケーパビリティ (capability) を持っていない。
EFAULT cmd 引き数に IPC_SET か IPC_STAT が指定されたが buf で指されてい
るアドレスにアクセスできない。
EIDRM shmid が削除 (remove) された識別子 (identifier) を指している。
EINVAL shmid が有効な識別子でないか、 cmd が有効なコマンドでない。も し
く は、 SHM_STAT 操作の場合に、 shmid で指定されたインデックス値
が現在未使用の配列のスロットを参照していた。
ENOMEM (2.6.9 以降のカーネルにおいて) SHM_LOCK が指定され、ロックされる
予定のセグメントのサイズ (ロックされる共有メモリ・セグメントの合
計バイト数) が、呼び出したプロセスの実ユーザー ID についての制限
を 超 えた。この制限は RLIMIT_MEMLOCK ソフト資源制限で定義される
(setrlimit(2) を参照)。
EOVERFLOW
IPC_STAT が試みられ、GID や UID の値が buf で指示される構造体 に
格納するには大き過ぎる。
EPERM IPC_SET か IPC_RMID が試みられ、呼び出したプロセスの実効ユーザー
ID が作成者 (shm_perm.cuid) でも所有者 (shm_perm.uid) でもなく、
プ ロセスが特権を持たない (Linux では CAP_SYS_ADMIN ケーパビリテ
ィを持たない)。
または (2.6.9 より前のカーネルで) SHM_LOCK または SHM_UNLOCK が
指 定 さ れ て い る が 、 プ ロセスが特権を持たない (Linux では
CAP_IPC_LOCK ケーパビリティを持たない)。 (Linux 2.6.9 以降では、
RLIMIT_MEMLOCK が 0 で呼び出し元が特権を持たない場合にも、このエ
ラーが起こる。)
準拠
SVr4, POSIX.1-2001.
注意
IPC_INFO, SHM_STAT, SHM_INFO 操作は、 ipcs(8) プログラムで割り当て済 の
資 源に関する情報を提供するために使用されている。将来、これらの操作は変
更されたり、 /proc ファイルシステムのインタフェースに移動されるかもしれ
ない。
Linux では、 shmctl(IPC_RMID) を使ってすでに削除マークがつけられている
共有メモリ・セグメントをあるプロセスが付加 (attach) (shmat(2)) すること
を 許可している。この機能は他の Unix の実装では利用できない。移植性を考
慮したアプリケーションではこれに依存しないようにすべきである。
構造体 shmid_ds 内の多くのフィールドは、 Linux 2.2 では short 型だっ た
が 、Linux 2.4 では long 型になった。この利点を生かすには、glibc-2.1.91
以降の環境下で再コンパイルすれば十分である。カーネルは新しい形式の呼 び
出しと古い形式の呼び出しを cmd 内の IPC_64 フラグで区別する。
関連項目
mlock(2), setrlimit(2), shmget(2), shmop(2), capabilities(7),
shm_overview(7), svipc(7)
Linux 2008-08-07 SHMCTL(2)
SHMCTL(2) Linux Programmer’s Manual SHMCTL(2)
NAME
shmctl - shared memory control
SYNOPSIS
#include
#include
int shmctl(int shmid, int cmd, struct shmid_ds *buf);
DESCRIPTION
shmctl() performs the control operation specified by cmd on the shared
memory segment whose identifier is given in shmid.
The buf argument is a pointer to a shmid_ds structure, defined in
as follows:
struct shmid_ds {
struct ipc_perm shm_perm; /* Ownership and permissions */
size_t shm_segsz; /* Size of segment (bytes) */
time_t shm_atime; /* Last attach time */
time_t shm_dtime; /* Last detach time */
time_t shm_ctime; /* Last change time */
pid_t shm_cpid; /* PID of creator */
pid_t shm_lpid; /* PID of last shmat(2)/shmdt(2) */
shmatt_t shm_nattch; /* No. of current attaches */
...
};
The ipc_perm structure is defined in as follows (the high-
lighted fields are settable using IPC_SET):
struct ipc_perm {
key_t __key; /* Key supplied to shmget(2) */
uid_t uid; /* Effective UID of owner */
gid_t gid; /* Effective GID of owner */
uid_t cuid; /* Effective UID of creator */
gid_t cgid; /* Effective GID of creator */
unsigned short mode; /* Permissions + SHM_DEST and
SHM_LOCKED flags */
unsigned short __seq; /* Sequence number */
};
Valid values for cmd are:
IPC_STAT Copy information from the kernel data structure associated
with shmid into the shmid_ds structure pointed to by buf.
The caller must have read permission on the shared memory
segment.
IPC_SET Write the values of some members of the shmid_ds structure
pointed to by buf to the kernel data structure associated
with this shared memory segment, updating also its shm_ctime
member. The following fields can be changed: shm_perm.uid,
shm_perm.gid, and (the least significant 9 bits of)
shm_perm.mode. The effective UID of the calling process must
match the owner (shm_perm.uid) or creator (shm_perm.cuid) of
the shared memory segment, or the caller must be privileged.
IPC_RMID Mark the segment to be destroyed. The segment will only
actually be destroyed after the last process detaches it
(i.e., when the shm_nattch member of the associated structure
shmid_ds is zero). The caller must be the owner or creator,
or be privileged. If a segment has been marked for destruc-
tion, then the (non-standard) SHM_DEST flag of the
shm_perm.mode field in the associated data structure
retrieved by IPC_STAT will be set.
The caller must ensure that a segment is eventually destroyed; other-
wise its pages that were faulted in will remain in memory or swap.
IPC_INFO (Linux-specific)
Returns information about system-wide shared memory limits
and parameters in the structure pointed to by buf. This
structure is of type shminfo (thus, a cast is required),
defined in if the _GNU_SOURCE feature test macro
is defined:
struct shminfo {
unsigned long shmmax; /* Maximum segment size */
unsigned long shmmin; /* Minimum segment size;
always 1 */
unsigned long shmmni; /* Maximum number of segments */
unsigned long shmseg; /* Maximum number of segments
that a process can attach;
unused within kernel */
unsigned long shmall; /* Maximum number of pages of
shared memory, system-wide */
};
The shmmni, shmmax, and shmall settings can be changed via
/proc files of the same name; see proc(5) for details.
SHM_INFO (Linux-specific)
Returns a shm_info structure whose fields contain information
about system resources consumed by shared memory. This
structure is defined in if the _GNU_SOURCE fea-
ture test macro is defined:
struct shm_info {
int used_ids; /* # of currently existing
segments */
unsigned long shm_tot; /* Total number of shared
memory pages */
unsigned long shm_rss; /* # of resident shared
memory pages */
unsigned long shm_swp; /* # of swapped shared
memory pages */
unsigned long swap_attempts;
/* Unused since Linux 2.4 */
unsigned long swap_successes;
/* Unused since Linux 2.4 */
};
SHM_STAT (Linux-specific)
Returns a shmid_ds structure as for IPC_STAT. However, the
shmid argument is not a segment identifier, but instead an
index into the kernel’s internal array that maintains infor-
mation about all shared memory segments on the system.
The caller can prevent or allow swapping of a shared memory segment
with the following cmd values:
SHM_LOCK (Linux-specific)
Prevent swapping of the shared memory segment. The caller
must fault in any pages that are required to be present after
locking is enabled. If a segment has been locked, then the
(non-standard) SHM_LOCKED flag of the shm_perm.mode field in
the associated data structure retrieved by IPC_STAT will be
set.
SHM_UNLOCK (Linux-specific)
Unlock the segment, allowing it to be swapped out.
In kernels before 2.6.10, only a privileged process could employ
SHM_LOCK and SHM_UNLOCK. Since kernel 2.6.10, an unprivileged process
can employ these operations if its effective UID matches the owner or
creator UID of the segment, and (for SHM_LOCK) the amount of memory to
be locked falls within the RLIMIT_MEMLOCK resource limit (see setr-
limit(2)).
RETURN VALUE
A successful IPC_INFO or SHM_INFO operation returns the index of the
highest used entry in the kernel’s internal array recording information
about all shared memory segments. (This information can be used with
repeated SHM_STAT operations to obtain information about all shared
memory segments on the system.) A successful SHM_STAT operation
returns the identifier of the shared memory segment whose index was
given in shmid. Other operations return 0 on success.
On error, -1 is returned, and errno is set appropriately.
ERRORS
EACCES IPC_STAT or SHM_STAT is requested and shm_perm.mode does not
allow read access for shmid, and the calling process does not
have the CAP_IPC_OWNER capability.
EFAULT The argument cmd has value IPC_SET or IPC_STAT but the address
pointed to by buf isn’t accessible.
EIDRM shmid points to a removed identifier.
EINVAL shmid is not a valid identifier, or cmd is not a valid command.
Or: for a SHM_STAT operation, the index value specified in shmid
referred to an array slot that is currently unused.
ENOMEM (In kernels since 2.6.9), SHM_LOCK was specified and the size of
the to-be-locked segment would mean that the total bytes in
locked shared memory segments would exceed the limit for the
real user ID of the calling process. This limit is defined by
the RLIMIT_MEMLOCK soft resource limit (see setrlimit(2)).
EOVERFLOW
IPC_STAT is attempted, and the GID or UID value is too large to
be stored in the structure pointed to by buf.
EPERM IPC_SET or IPC_RMID is attempted, and the effective user ID of
the calling process is not that of the creator (found in
shm_perm.cuid), or the owner (found in shm_perm.uid), and the
process was not privileged (Linux: did not have the
CAP_SYS_ADMIN capability).
Or (in kernels before 2.6.9), SHM_LOCK or SHM_UNLOCK was speci-
fied, but the process was not privileged (Linux: did not have
the CAP_IPC_LOCK capability). (Since Linux 2.6.9, this error
can also occur if the RLIMIT_MEMLOCK is 0 and the caller is not
privileged.)
CONFORMING TO
SVr4, POSIX.1-2001.
NOTES
The IPC_INFO, SHM_STAT and SHM_INFO operations are used by the ipcs(8)
program to provide information on allocated resources. In the future
these may modified or moved to a /proc file system interface.
Linux permits a process to attach (shmat(2)) a shared memory segment
that has already been marked for deletion using shmctl(IPC_RMID). This
feature is not available on other Unix implementations; portable appli-
cations should avoid relying on it.
Various fields in a struct shmid_ds were typed as short under Linux 2.2
and have become long under Linux 2.4. To take advantage of this, a
recompilation under glibc-2.1.91 or later should suffice. (The kernel
distinguishes old and new calls by an IPC_64 flag in cmd.)
SEE ALSO
mlock(2), setrlimit(2), shmget(2), shmop(2), capabilities(7), svipc(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 2008-08-07 SHMCTL(2)