1 .\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993
2 .\" and Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
3 .\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
5 .\" %%%LICENSE_START(VERBATIM)
6 .\" Permission is granted to make and distribute verbatim copies of this
7 .\" manual provided the copyright notice and this permission notice are
8 .\" preserved on all copies.
10 .\" Permission is granted to copy and distribute modified versions of this
11 .\" manual under the conditions for verbatim copying, provided that the
12 .\" entire resulting derived work is distributed under the terms of a
13 .\" permission notice identical to this one.
15 .\" Since the Linux kernel and libraries are constantly changing, this
16 .\" manual page may be incorrect or out-of-date. The author(s) assume no
17 .\" responsibility for errors or omissions, or for damages resulting from
18 .\" the use of the information contained herein. The author(s) may not
19 .\" have taken the same level of care in the production of this manual,
20 .\" which is licensed free of charge, as they might when working
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
27 .\" Modified 1993-07-28, Rik Faith <faith@cs.unc.edu>
28 .\" Modified 1993-11-28, Giorgio Ciucci <giorgio@crcc.it>
29 .\" Modified 1997-01-31, Eric S. Raymond <esr@thyrsus.com>
30 .\" Modified 2001-02-18, Andries Brouwer <aeb@cwi.nl>
31 .\" Modified 2002-01-05, 2004-05-27, 2004-06-17,
32 .\" Michael Kerrisk <mtk.manpages@gmail.com>
33 .\" Modified 2004-10-11, aeb
34 .\" Modified, Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
35 .\" Language and formatting clean-ups
36 .\" Updated shmid_ds structure definitions
37 .\" Added information on SHM_DEST and SHM_LOCKED flags
38 .\" Noted that CAP_IPC_LOCK is not required for SHM_UNLOCK
39 .\" since kernel 2.6.9
40 .\" Modified, 2004-11-25, mtk, notes on 2.6.9 RLIMIT_MEMLOCK changes
41 .\" 2005-04-25, mtk -- noted aberrant Linux behavior w.r.t. new
42 .\" attaches to a segment that has already been marked for deletion.
43 .\" 2005-08-02, mtk: Added IPC_INFO, SHM_INFO, SHM_STAT descriptions.
45 .TH SHMCTL 2 2015-08-08 "Linux" "Linux Programmer's Manual"
47 shmctl \- System V shared memory control
50 .B #include <sys/ipc.h>
52 .B #include <sys/shm.h>
54 .BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf );
58 performs the control operation specified by
60 on the System\ V shared memory segment whose identifier is given in
65 argument is a pointer to a \fIshmid_ds\fP structure,
66 defined in \fI<sys/shm.h>\fP as follows:
71 struct ipc_perm shm_perm; /* Ownership and permissions */
72 size_t shm_segsz; /* Size of segment (bytes) */
73 time_t shm_atime; /* Last attach time */
74 time_t shm_dtime; /* Last detach time */
75 time_t shm_ctime; /* Last change time */
76 pid_t shm_cpid; /* PID of creator */
77 pid_t shm_lpid; /* PID of last shmat(2)/shmdt(2) */
78 shmatt_t shm_nattch; /* No. of current attaches */
86 structure is defined as follows
87 (the highlighted fields are settable using
93 key_t __key; /* Key supplied to shmget(2) */
94 uid_t \fBuid\fP; /* Effective UID of owner */
95 gid_t \fBgid\fP; /* Effective GID of owner */
96 uid_t cuid; /* Effective UID of creator */
97 gid_t cgid; /* Effective GID of creator */
98 unsigned short \fBmode\fP; /* \fBPermissions\fP + SHM_DEST and
100 unsigned short __seq; /* Sequence number */
111 Copy information from the kernel data structure associated with
115 structure pointed to by \fIbuf\fP.
116 The caller must have read permission on the
117 shared memory segment.
120 Write the values of some members of the
122 structure pointed to by
124 to the kernel data structure associated with this shared memory segment,
128 The following fields can be changed:
129 \fIshm_perm.uid\fP, \fIshm_perm.gid\fP,
130 and (the least significant 9 bits of) \fIshm_perm.mode\fP.
131 The effective UID of the calling process must match the owner
134 .RI ( shm_perm.cuid )
135 of the shared memory segment, or the caller must be privileged.
138 Mark the segment to be destroyed.
139 The segment will actually be destroyed
140 only after the last process detaches it (i.e., when the
142 member of the associated structure
145 The caller must be the owner or creator of the segment, or be privileged.
150 If a segment has been marked for destruction, then the (nonstandard)
154 field in the associated data structure retrieved by
158 The caller \fImust\fP ensure that a segment is eventually destroyed;
159 otherwise its pages that were faulted in will remain in memory or swap.
161 See also the description of
162 .I /proc/sys/kernel/shm_rmid_forced
166 .BR IPC_INFO " (Linux-specific)"
167 Return information about system-wide shared memory limits and
168 parameters in the structure pointed to by
170 This structure is of type
172 (thus, a cast is required),
177 feature test macro is defined:
182 unsigned long shmmax; /* Maximum segment size */
183 unsigned long shmmin; /* Minimum segment size;
185 unsigned long shmmni; /* Maximum number of segments */
186 unsigned long shmseg; /* Maximum number of segments
187 that a process can attach;
188 unused within kernel */
189 unsigned long shmall; /* Maximum number of pages of
190 shared memory, system-wide */
200 settings can be changed via
202 files of the same name; see
206 .BR SHM_INFO " (Linux-specific)"
209 structure whose fields contain information
210 about system resources consumed by shared memory.
211 This structure is defined in
215 feature test macro is defined:
220 int used_ids; /* # of currently existing
222 unsigned long shm_tot; /* Total number of shared
224 unsigned long shm_rss; /* # of resident shared
226 unsigned long shm_swp; /* # of swapped shared
228 unsigned long swap_attempts;
229 /* Unused since Linux 2.4 */
230 unsigned long swap_successes;
231 /* Unused since Linux 2.4 */
236 .BR SHM_STAT " (Linux-specific)"
243 argument is not a segment identifier, but instead an index into
244 the kernel's internal array that maintains information about
245 all shared memory segments on the system.
247 The caller can prevent or allow swapping of a shared
248 memory segment with the following \fIcmd\fP values:
251 .BR SHM_LOCK " (Linux-specific)"
252 Prevent swapping of the shared memory segment.
253 The caller must fault in
254 any pages that are required to be present after locking is enabled.
255 If a segment has been locked, then the (nonstandard)
259 field in the associated data structure retrieved by
263 .BR SHM_UNLOCK " (Linux-specific)"
264 Unlock the segment, allowing it to be swapped out.
266 In kernels before 2.6.10, only a privileged process
271 Since kernel 2.6.10, an unprivileged process can employ these operations
272 if its effective UID matches the owner or creator UID of the segment, and
275 the amount of memory to be locked falls within the
279 .\" There was some weirdness in 2.6.9: SHM_LOCK and SHM_UNLOCK could
280 .\" be applied to a segment, regardless of ownership of the segment.
281 .\" This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed
282 .\" in 2.6.10. MTK, May 2005
288 operation returns the index of the highest used entry in the
289 kernel's internal array recording information about all
290 shared memory segments.
291 (This information can be used with repeated
293 operations to obtain information about all shared memory segments
297 operation returns the identifier of the shared memory segment
298 whose index was given in
300 Other operations return 0 on success.
302 On error, \-1 is returned, and
304 is set appropriately.
308 \fBIPC_STAT\fP or \fBSHM_STAT\fP is requested and
309 \fIshm_perm.mode\fP does not allow read access for
311 and the calling process does not have the
322 but the address pointed to by
327 \fIshmid\fP points to a removed identifier.
330 \fIshmid\fP is not a valid identifier, or \fIcmd\fP
331 is not a valid command.
334 operation, the index value specified in
336 referred to an array slot that is currently unused.
339 (In kernels since 2.6.9),
341 was specified and the size of the to-be-locked segment would mean
342 that the total bytes in locked shared memory segments would exceed
343 the limit for the real user ID of the calling process.
344 This limit is defined by the
346 soft resource limit (see
350 \fBIPC_STAT\fP is attempted, and the GID or UID value
351 is too large to be stored in the structure pointed to by
355 \fBIPC_SET\fP or \fBIPC_RMID\fP is attempted, and the
356 effective user ID of the calling process is not that of the creator
362 and the process was not privileged (Linux: did not have the
366 Or (in kernels before 2.6.9),
370 was specified, but the process was not privileged
371 (Linux: did not have the
374 (Since Linux 2.6.9, this error can also occur if the
376 is 0 and the caller is not privileged.)
378 POSIX.1-2001, POSIX.1-2008, SVr4.
379 .\" SVr4 documents additional error conditions EINVAL,
380 .\" ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents
381 .\" an EIDRM error condition.
387 isn't required on Linux or by any version of POSIX.
389 some old implementations required the inclusion of these header files,
390 and the SVID also documented their inclusion.
391 Applications intended to be portable to such old systems may need
392 to include these header files.
393 .\" Like Linux, the FreeBSD man pages still document
394 .\" the inclusion of these header files.
401 operations are used by the
403 program to provide information on allocated resources.
404 In the future, these may modified or moved to a
406 filesystem interface.
408 Linux permits a process to attach
410 a shared memory segment that has already been marked for deletion
412 .IR shmctl(IPC_RMID) .
413 This feature is not available on other UNIX implementations;
414 portable applications should avoid relying on it.
416 Various fields in a \fIstruct shmid_ds\fP were typed as
422 To take advantage of this,
423 a recompilation under glibc-2.1.91 or later should suffice.
424 (The kernel distinguishes old and new calls by an
433 .BR capabilities (7),