shmctl — System V shared memory control
#include <sys/ipc.h> #include <sys/shm.h>
int
shmctl( |
int shmid, |
| int cmd, | |
struct shmid_ds *buf); |
shmctl() performs the
control operation specified by cmd on the System V shared
memory segment whose identifier is given in shmid.
The buf argument
is a pointer to a shmid_ds
structure, defined in <sys/shm.h>
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 as follows (the highlighted fields are
settable using IPC_SET):
struct ipc_perm { key_t __key;uid_t uid;gid_t gid;uid_t cuid;gid_t cgid;unsigned short mode;
SHM_LOCKED flags */unsigned short __seq;};
Valid values for cmd are:
IPC_STATCopy 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_SETWrite 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_RMIDMark the segment to be destroyed. The segment will
actually be destroyed only 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 of the segment, or be
privileged. The buf argument is
ignored.
If a segment has been marked for destruction, then
the (nonstandard) 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; otherwise its pages
that were faulted in will remain in memory or swap.
See also the description of /proc/sys/kernel/shm_rmid_forced in
proc(5).
IPC_INFO (Linux-specific)Return 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 <sys/shm.h> if the _GNU_SOURCE feature test macro is
defined:
struct shminfo { unsigned long shmmax;unsigned long shmmin;
always 1 */unsigned long shmmni;unsigned long shmseg;
that a process can attach;
unused within kernel */unsigned long shmall;
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)Return a shm_info structure
whose fields contain information about system resources
consumed by shared memory. This structure is defined in
<sys/shm.h> if the _GNU_SOURCE feature test macro is
defined:
struct shm_info { int used_ids;
segments */unsigned long shm_tot;
memory pages */unsigned long shm_rss;
memory pages */unsigned long shm_swp;
memory pages */unsigned long swap_attempts;unsigned long swap_successes;};
SHM_STAT (Linux-specific)Return 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 information
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 (nonstandard) 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
setrlimit(2)).
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.
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.
The argument cmd has value
IPC_SET or IPC_STAT but the address pointed to
by buf isn't
accessible.
shmid points
to a removed identifier.
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.
(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)).
IPC_STAT is attempted,
and the GID or UID value is too large to be stored in
the structure pointed to by buf.
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 specified, 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.)
The inclusion of <sys/types.h> and <sys/ipc.h>
isn't required on Linux or by any version of POSIX. However,
some old implementations required the inclusion of these
header files, and the SVID also documented their inclusion.
Applications intended to be portable to such old systems may
need to include these header files.
The IPC_INFO, SHM_STAT and SHM_INFO operations are used by the
ipcs(1) program to provide
information on allocated resources. In the future, these may
modified or moved to a /proc
filesystem 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 applications 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.)
This page is part of release 4.07 of the Linux man-pages project. A
description of the project, information about reporting bugs,
and the latest version of this page, can be found at
https://www.kernel.org/doc/man−pages/.
|
Copyright (c) 1993 Luigi P. Bai (lpbsoftint.com) July 28, 1993 and Copyright 1993 Giorgio Ciucci <giorgiocrcc.it> and Copyright 2004, 2005 Michael Kerrisk <mtk.manpagesgmail.com> %%%LICENSE_START(VERBATIM) 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. %%%LICENSE_END Modified 1993-07-28, Rik Faith <faithcs.unc.edu> Modified 1993-11-28, Giorgio Ciucci <giorgiocrcc.it> Modified 1997-01-31, Eric S. Raymond <esrthyrsus.com> Modified 2001-02-18, Andries Brouwer <aebcwi.nl> Modified 2002-01-05, 2004-05-27, 2004-06-17, Michael Kerrisk <mtk.manpagesgmail.com> Modified 2004-10-11, aeb Modified, Nov 2004, Michael Kerrisk <mtk.manpagesgmail.com> Language and formatting clean-ups Updated shmid_ds structure definitions Added information on SHM_DEST and SHM_LOCKED flags Noted that CAP_IPC_LOCK is not required for SHM_UNLOCK since kernel 2.6.9 Modified, 2004-11-25, mtk, notes on 2.6.9 RLIMIT_MEMLOCK changes 2005-04-25, mtk -- noted aberrant Linux behavior w.r.t. new attaches to a segment that has already been marked for deletion. 2005-08-02, mtk: Added IPC_INFO, SHM_INFO, SHM_STAT descriptions. |