2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993
|
|
|
|
.\" Portions Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
|
2006-02-15 23:15:29 +00:00
|
|
|
.\" Portions Copyright 2004, 2005 Michael Kerrisk <mtk-manpages@gmx.net>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
|
|
|
.\" 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.
|
2004-11-10 17:27:34 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" 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.
|
2004-11-10 17:27:34 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
|
|
|
.\" Modified 1993-07-28, Rik Faith <faith@cs.unc.edu>
|
|
|
|
.\" Modified 1993-11-28, Giorgio Ciucci <giorgio@crcc.it>
|
|
|
|
.\" Modified 1997-01-31, Eric S. Raymond <esr@thyrsus.com>
|
|
|
|
.\" Modified 2001-02-18, Andries Brouwer <aeb@cwi.nl>
|
|
|
|
.\" Modified 2002-01-05, 2004-05-27, 2004-06-17,
|
2004-11-03 14:43:40 +00:00
|
|
|
.\" Michael Kerrisk <mtk-manpages@gmx.net>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Modified 2004-10-11, aeb
|
2004-11-23 10:06:02 +00:00
|
|
|
.\" Modified, Nov 2004, Michael Kerrisk <mtk-manpages@gmx.net>
|
2004-11-10 17:27:34 +00:00
|
|
|
.\" Language and formatting clean-ups
|
|
|
|
.\" Updated shmid_ds structure definitions
|
|
|
|
.\" Added information on SHM_DEST and SHM_LOCKED flags
|
2004-11-23 10:06:02 +00:00
|
|
|
.\" Noted that CAP_IPC_LOCK is not required for SHM_UNLOCK
|
|
|
|
.\" since kernel 2.6.9
|
2004-11-25 13:38:17 +00:00
|
|
|
.\" Modified, 2004-11-25, mtk, notes on 2.6.9 RLIMIT_MEMLOCK changes
|
2005-04-25 08:36:43 +00:00
|
|
|
.\" 2005-04-25, mtk -- noted aberrant Linux behaviour w.r.t. new
|
|
|
|
.\" attaches to a segment that has already been marked for deletion.
|
2005-08-02 12:09:50 +00:00
|
|
|
.\" 2005-08-02, mtk: Added IPC_INFO, SHM_INFO, SHM_STAT descriptions.
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
2005-05-30 11:58:06 +00:00
|
|
|
.TH SHMCTL 2 2005-05-30 Linux 2.6.11" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
shmctl \- shared memory control
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.ad l
|
|
|
|
.B #include <sys/ipc.h>
|
|
|
|
.sp
|
|
|
|
.B #include <sys/shm.h>
|
|
|
|
.sp
|
|
|
|
.BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf );
|
|
|
|
.ad b
|
|
|
|
.SH DESCRIPTION
|
2004-12-13 08:39:28 +00:00
|
|
|
.BR shmctl ()
|
2004-11-10 17:27:34 +00:00
|
|
|
allows the caller to obtain information about a shared memory segment,
|
|
|
|
set the owner, group, and permissions of a segment,
|
|
|
|
or destroy a segment.
|
|
|
|
.PP
|
|
|
|
The
|
|
|
|
.I buf
|
|
|
|
argument is a pointer to a \fIshmid_ds\fP structure,
|
|
|
|
defined in <sys/shm.h> as follows:
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
.in +4n
|
|
|
|
.nf
|
|
|
|
struct shmid_ds {
|
2004-11-10 17:27:34 +00:00
|
|
|
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 */
|
2005-04-18 13:35:29 +00:00
|
|
|
pid_t shm_lpid; /* PID of last shmat()/shmdt() */
|
2004-11-10 17:27:34 +00:00
|
|
|
shmatt_t shm_nattch; /* No. of current attaches */
|
2004-11-03 13:51:07 +00:00
|
|
|
...
|
|
|
|
};
|
|
|
|
.fi
|
|
|
|
.in -4n
|
|
|
|
.PP
|
2004-11-10 17:27:34 +00:00
|
|
|
The
|
|
|
|
.I ipc_perm
|
|
|
|
structure is defined in <sys/ipc.h> as follows
|
|
|
|
(the highlighted fields are settable using
|
|
|
|
.BR IPC_SET ):
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
.in +4n
|
|
|
|
.nf
|
|
|
|
struct ipc_perm {
|
2004-11-10 17:27:34 +00:00
|
|
|
key_t key; /* Key supplied to shmget() */
|
|
|
|
uid_t \fBuid\fP; /* Effective UID of owner */
|
|
|
|
gid_t \fBgid\fP; /* Effective GID of owner */
|
|
|
|
uid_t cuid; /* Effective UID of creator */
|
|
|
|
gid_t cgid; /* Effective GID of creator */
|
|
|
|
unsigned short \fBmode\fP; /* \fBPermissions\fP + SHM_DEST and
|
|
|
|
SHM_LOCKED flags */
|
|
|
|
unsigned short seq; /* Sequence number */
|
2004-11-03 13:51:07 +00:00
|
|
|
};
|
|
|
|
.fi
|
|
|
|
.in -4n
|
|
|
|
.PP
|
2004-11-10 17:27:34 +00:00
|
|
|
Valid values for
|
|
|
|
.I cmd
|
|
|
|
are:
|
2004-11-03 13:51:07 +00:00
|
|
|
.br
|
|
|
|
.TP 12
|
|
|
|
.B IPC_STAT
|
2004-11-10 17:27:34 +00:00
|
|
|
Copy information from the kernel data structure associated with
|
|
|
|
.I shmid
|
|
|
|
into the
|
|
|
|
.I shmid_ds
|
|
|
|
structure pointed to by \fIbuf\fP.
|
|
|
|
The caller must have read permission on the
|
2004-11-03 13:51:07 +00:00
|
|
|
shared memory segment.
|
|
|
|
.TP
|
|
|
|
.B IPC_SET
|
2004-11-10 17:27:34 +00:00
|
|
|
Write the values of some members of the
|
|
|
|
.I shmid_ds
|
|
|
|
structure pointed to by
|
|
|
|
.I arg.buf
|
|
|
|
to the kernel data structure associated with this shared memory segment,
|
|
|
|
updating also its
|
2004-11-03 13:51:07 +00:00
|
|
|
.I shm_ctime
|
2004-11-10 17:27:34 +00:00
|
|
|
member.
|
|
|
|
The following fields can be changed:
|
2005-04-25 08:36:43 +00:00
|
|
|
\fIshm_perm.uid\fP, \fIshm_perm.gid\fP,
|
|
|
|
and (the least significant 9 bits of) \fIshm_perm.mode\fP.
|
2004-11-10 17:27:34 +00:00
|
|
|
The effective UID of the calling process must match the owner
|
|
|
|
.RI ( shm_perm.uid )
|
|
|
|
or creator
|
|
|
|
.RI ( shm_perm.cuid )
|
|
|
|
of the shared memory segment, or the caller must be privileged.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B IPC_RMID
|
2004-11-10 17:27:34 +00:00
|
|
|
Mark the segment to be destroyed.
|
|
|
|
The segment will only actually be destroyed
|
|
|
|
after the last process detaches it (i.e., when the
|
2004-11-03 13:51:07 +00:00
|
|
|
.I shm_nattch
|
|
|
|
member of the associated structure
|
|
|
|
.I shmid_ds
|
2004-11-10 17:27:34 +00:00
|
|
|
is zero).
|
|
|
|
The caller must be the owner or creator, or be privileged.
|
|
|
|
If a segment has been marked for destruction, then the (non-standard)
|
|
|
|
.B SHM_DEST
|
|
|
|
flag of the
|
|
|
|
.I shm_perm.mode
|
|
|
|
field in the associated data structure retrieved by
|
|
|
|
.B IPC_STAT
|
|
|
|
will be set.
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
2004-11-10 17:27:34 +00:00
|
|
|
The caller \fImust\fP ensure that a segment is eventually destroyed;
|
|
|
|
otherwise its pages that were faulted in will remain in memory or swap.
|
2005-08-02 12:09:50 +00:00
|
|
|
.TP
|
|
|
|
.BR IPC_INFO " (Linux specific)"
|
|
|
|
Returns information about system-wide shared memory limits and
|
|
|
|
parameters in the structure pointed to by
|
|
|
|
.IR buf .
|
|
|
|
This structure is of type
|
|
|
|
.IR shminfo
|
|
|
|
(thus, a cast is required),
|
|
|
|
defined in
|
|
|
|
.I <sys/shm.h>
|
|
|
|
if the _GNU_SOURCE feature test macro is defined:
|
|
|
|
.nf
|
|
|
|
.in +2n
|
|
|
|
|
|
|
|
struct shminfo {
|
|
|
|
unsigned long shmmax; /* Max. segment size */
|
|
|
|
unsigned long shmmin; /* Min. segment size; always 1 */
|
|
|
|
unsigned long shmmni; /* Max. # of segments */
|
|
|
|
unsigned long shmseg; /* Max. # of segments that a
|
|
|
|
process can attach; unused */
|
|
|
|
unsigned long shmall; /* Max. # of pages of shared
|
|
|
|
memory, system-wide */
|
|
|
|
};
|
|
|
|
|
|
|
|
.in -2n
|
|
|
|
.fi
|
|
|
|
The
|
|
|
|
.IR shmmni ,
|
|
|
|
.IR shmmax ,
|
2005-05-30 11:58:06 +00:00
|
|
|
and
|
2005-08-02 12:09:50 +00:00
|
|
|
.I shmall
|
|
|
|
settings can be changed via
|
|
|
|
.I /proc
|
|
|
|
files of the same name; see
|
|
|
|
.BR proc (5)
|
|
|
|
for details.
|
|
|
|
.TP
|
|
|
|
.BR SHM_INFO " (Linux specific)"
|
|
|
|
Returns a
|
|
|
|
.I shm_info
|
2005-08-02 12:12:52 +00:00
|
|
|
structure whose fields contain information
|
2005-08-02 12:09:50 +00:00
|
|
|
about system resources consumed by shared memory.
|
|
|
|
This structure is defined in
|
|
|
|
.I <sys/shm.h>
|
|
|
|
if the _GNU_SOURCE feature test macro is defined:
|
|
|
|
.nf
|
|
|
|
.in +2n
|
|
|
|
|
|
|
|
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 */
|
|
|
|
};
|
|
|
|
|
|
|
|
.in -2n
|
|
|
|
.fi
|
|
|
|
.TP
|
|
|
|
.BR SHM_STAT " (Linux specific)"
|
|
|
|
Returns a
|
|
|
|
.I shmid_ds
|
|
|
|
structure as for
|
|
|
|
.BR IPC_STAT .
|
|
|
|
However, the
|
|
|
|
.I 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.
|
2005-05-30 11:58:06 +00:00
|
|
|
.PP
|
|
|
|
The caller can prevent or allow swapping of a shared
|
2004-11-10 17:27:34 +00:00
|
|
|
memory segment with the following \fIcmd\fP values:
|
2004-11-03 13:51:07 +00:00
|
|
|
.br
|
|
|
|
.TP 12
|
2005-08-02 12:09:50 +00:00
|
|
|
.BR SHM_LOCK " (Linux specific)"
|
2004-11-10 17:27:34 +00:00
|
|
|
Prevent swapping of the shared memory segment. The caller must fault in
|
2004-11-03 13:51:07 +00:00
|
|
|
any pages that are required to be present after locking is enabled.
|
2004-11-10 17:27:34 +00:00
|
|
|
If a segment has been locked, then the (non-standard)
|
2005-08-02 12:09:50 +00:00
|
|
|
.BR SHM_LOCKED
|
2004-11-10 17:27:34 +00:00
|
|
|
flag of the
|
|
|
|
.I shm_perm.mode
|
|
|
|
field in the associated data structure retrieved by
|
|
|
|
.B IPC_STAT
|
|
|
|
will be set.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2005-08-02 12:09:50 +00:00
|
|
|
.BR SHM_UNLOCK " (Linux specific)"
|
2004-11-10 17:27:34 +00:00
|
|
|
Unlock the segment, allowing it to be swapped out.
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
2005-05-30 11:58:06 +00:00
|
|
|
In kernels before 2.6.10, only a privileged process
|
|
|
|
could employ
|
|
|
|
.B SHM_LOCK
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-05-30 11:58:06 +00:00
|
|
|
.BR 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
|
|
|
|
.BR SHM_LOCK )
|
|
|
|
the amount of memory to be locked falls within the
|
|
|
|
.BR RLIMIT_MEMLOCK
|
|
|
|
resource limit (see
|
|
|
|
.BR setrlimit (2)).
|
|
|
|
.\" There was some weirdness in 2.6.9: SHM_LOCK and SHM_UNLOCK could
|
|
|
|
.\" be applied to a segment, regardless of ownership of the segment.
|
|
|
|
.\" This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed
|
|
|
|
.\" in 2.6.10. MTK, May 2005
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "RETURN VALUE"
|
2005-08-02 12:09:50 +00:00
|
|
|
A successful
|
|
|
|
.B IPC_INFO
|
|
|
|
or
|
|
|
|
.B 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
|
|
|
|
.B SHM_STAT
|
|
|
|
operations to obtain information about all shared memory segments
|
|
|
|
on the system.)
|
|
|
|
A successful
|
|
|
|
.B SHM_STAT
|
|
|
|
operation returns the identifier of the shared memory segment
|
|
|
|
whose index was given in
|
|
|
|
.IR shmid .
|
|
|
|
Other operations return 0 on success.
|
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
On error, \-1 is returned, and
|
|
|
|
.I errno
|
|
|
|
is set appropriately.
|
|
|
|
.SH ERRORS
|
|
|
|
.TP 11
|
|
|
|
.B EACCES
|
|
|
|
\fBIPC_STAT\fP or \fBSHM_STAT\fP is requested and
|
2005-04-25 08:36:43 +00:00
|
|
|
\fIshm_perm.mode\fP does not allow read access for
|
2004-11-03 13:51:07 +00:00
|
|
|
.IR shmid ,
|
|
|
|
and the calling process does not have the
|
|
|
|
.BR CAP_IPC_OWNER
|
|
|
|
capability.
|
|
|
|
.TP
|
|
|
|
.B EFAULT
|
|
|
|
The argument
|
|
|
|
.I cmd
|
|
|
|
has value
|
|
|
|
.B IPC_SET
|
|
|
|
or
|
|
|
|
.B IPC_STAT
|
|
|
|
but the address pointed to by
|
|
|
|
.I buf
|
|
|
|
isn't accessible.
|
|
|
|
.TP
|
|
|
|
.B EIDRM
|
|
|
|
\fIshmid\fP points to a removed identifier.
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
\fIshmid\fP is not a valid identifier, or \fIcmd\fP
|
|
|
|
is not a valid command.
|
2005-08-02 12:09:50 +00:00
|
|
|
Or: for a
|
|
|
|
.B SHM_STAT
|
|
|
|
operation, the index value specified in
|
|
|
|
.I shmid
|
|
|
|
referred to an array slot that is currently unused.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
2004-11-25 13:38:17 +00:00
|
|
|
.B ENOMEM
|
|
|
|
(In kernels since 2.6.9),
|
|
|
|
.B 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
|
|
|
|
.BR RLIMIT_MEMLOCK
|
|
|
|
soft resource limit (see
|
|
|
|
.BR setrlimit (2)).
|
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
.B EOVERFLOW
|
2005-07-18 15:54:49 +00:00
|
|
|
\fBIPC_STAT\fP is attempted, and the GID or UID value
|
2004-11-03 13:51:07 +00:00
|
|
|
is too large to be stored in the structure pointed to by
|
2004-11-10 17:27:34 +00:00
|
|
|
.IR buf .
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EPERM
|
|
|
|
\fBIPC_SET\fP or \fBIPC_RMID\fP is attempted, and the
|
|
|
|
effective user ID of the calling process is not that of the creator
|
|
|
|
(found in
|
|
|
|
.IR shm_perm.cuid ),
|
|
|
|
or the owner
|
|
|
|
(found in
|
|
|
|
.IR shm_perm.uid ),
|
|
|
|
and the process was not privileged (Linux: did not have the
|
|
|
|
.B CAP_SYS_ADMIN
|
|
|
|
capability).
|
|
|
|
|
2004-11-25 13:38:17 +00:00
|
|
|
Or (in kernels before 2.6.9),
|
2004-11-03 13:51:07 +00:00
|
|
|
.B SHM_LOCK
|
|
|
|
or
|
|
|
|
.B SHM_UNLOCK
|
|
|
|
was specified, but the process was not privileged
|
|
|
|
(Linux: did not have the
|
|
|
|
.B CAP_IPC_LOCK
|
|
|
|
capability).
|
2004-11-25 13:38:17 +00:00
|
|
|
(Since Linux 2.6.9, this error can also occur if the
|
|
|
|
.BR RLIMIT_MEMLOCK
|
|
|
|
is 0 and the caller is not privileged.)
|
2005-04-25 08:36:43 +00:00
|
|
|
.SH NOTES
|
2005-08-02 12:09:50 +00:00
|
|
|
The
|
|
|
|
.BR IPC_INFO ,
|
|
|
|
.BR SHM_STAT
|
|
|
|
and
|
|
|
|
.B SHM_INFO
|
|
|
|
operations are used by the
|
|
|
|
.BR ipcs (8)
|
|
|
|
program to provide information on allocated resources.
|
|
|
|
In the future these may modified or moved to a /proc file system
|
|
|
|
interface.
|
|
|
|
|
2005-04-25 08:36:43 +00:00
|
|
|
Linux permits a process to attach
|
|
|
|
.RB ( shmat ())
|
|
|
|
a shared memory segment that has already been marked for deletion
|
|
|
|
using
|
|
|
|
.IR shmctl(IPC_RMID) .
|
|
|
|
This feature is not available on other Unix implementations;
|
|
|
|
portable applications should avoid relying on it.
|
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
Various fields in a \fIstruct shmid_ds\fP were shorts under Linux 2.2
|
|
|
|
and have become longs 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
|
|
|
|
.IR cmd .)
|
|
|
|
.SH "CONFORMING TO"
|
|
|
|
SVr4, SVID. SVr4 documents additional error conditions EINVAL,
|
|
|
|
ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents
|
|
|
|
an EIDRM error condition.
|
|
|
|
.SH "SEE ALSO"
|
2004-11-10 17:27:34 +00:00
|
|
|
.BR mlock (2),
|
2004-11-25 13:38:17 +00:00
|
|
|
.BR setrlimit (2),
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR shmget (2),
|
|
|
|
.BR shmop (2),
|
|
|
|
.BR capabilities (7)
|