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.
44 .\" 2018-03-20, dbueso: Added SHM_STAT_ANY description.
46 .TH SHMCTL 2 2017-09-15 "Linux" "Linux Programmer's Manual"
48 shmctl \- System V shared memory control
51 .B #include <sys/ipc.h>
53 .B #include <sys/shm.h>
55 .BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf );
59 performs the control operation specified by
61 on the System\ V shared memory segment whose identifier is given in
66 argument is a pointer to a \fIshmid_ds\fP structure,
67 defined in \fI<sys/shm.h>\fP as follows:
72 struct ipc_perm shm_perm; /* Ownership and permissions */
73 size_t shm_segsz; /* Size of segment (bytes) */
74 time_t shm_atime; /* Last attach time */
75 time_t shm_dtime; /* Last detach time */
76 time_t shm_ctime; /* Last change time */
77 pid_t shm_cpid; /* PID of creator */
78 pid_t shm_lpid; /* PID of last shmat(2)/shmdt(2) */
79 shmatt_t shm_nattch; /* No. of current attaches */
87 structure is defined as follows
88 (the highlighted fields are settable using
94 key_t __key; /* Key supplied to shmget(2) */
95 uid_t \fBuid\fP; /* Effective UID of owner */
96 gid_t \fBgid\fP; /* Effective GID of owner */
97 uid_t cuid; /* Effective UID of creator */
98 gid_t cgid; /* Effective GID of creator */
99 unsigned short \fBmode\fP; /* \fBPermissions\fP + SHM_DEST and
101 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 .BR SHM_STAT_ANY " (Linux-specific)"
254 is not checked for read access for
256 meaning that any user can employ this operation (just as any user may read
257 .IR /proc/sysvipc/shm
258 to obtain the same information).
260 The caller can prevent or allow swapping of a shared
261 memory segment with the following \fIcmd\fP values:
263 .BR SHM_LOCK " (Linux-specific)"
264 Prevent swapping of the shared memory segment.
265 The caller must fault in
266 any pages that are required to be present after locking is enabled.
267 If a segment has been locked, then the (nonstandard)
271 field in the associated data structure retrieved by
275 .BR SHM_UNLOCK " (Linux-specific)"
276 Unlock the segment, allowing it to be swapped out.
278 In kernels before 2.6.10, only a privileged process
283 Since kernel 2.6.10, an unprivileged process can employ these operations
284 if its effective UID matches the owner or creator UID of the segment, and
287 the amount of memory to be locked falls within the
291 .\" There was some weirdness in 2.6.9: SHM_LOCK and SHM_UNLOCK could
292 .\" be applied to a segment, regardless of ownership of the segment.
293 .\" This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed
294 .\" in 2.6.10. MTK, May 2005
300 operation returns the index of the highest used entry in the
301 kernel's internal array recording information about all
302 shared memory segments.
303 (This information can be used with repeated
307 operations to obtain information about all shared memory segments
311 operation returns the identifier of the shared memory segment
312 whose index was given in
314 Other operations return 0 on success.
316 On error, \-1 is returned, and
318 is set appropriately.
322 \fBIPC_STAT\fP or \fBSHM_STAT\fP is requested and
323 \fIshm_perm.mode\fP does not allow read access for
325 and the calling process does not have the
327 capability in the user namespace that governs its IPC namespace.
336 but the address pointed to by
341 \fIshmid\fP points to a removed identifier.
344 \fIshmid\fP is not a valid identifier, or \fIcmd\fP
345 is not a valid command.
350 operation, the index value specified in
352 referred to an array slot that is currently unused.
355 (In kernels since 2.6.9),
357 was specified and the size of the to-be-locked segment would mean
358 that the total bytes in locked shared memory segments would exceed
359 the limit for the real user ID of the calling process.
360 This limit is defined by the
362 soft resource limit (see
366 \fBIPC_STAT\fP is attempted, and the GID or UID value
367 is too large to be stored in the structure pointed to by
371 \fBIPC_SET\fP or \fBIPC_RMID\fP is attempted, and the
372 effective user ID of the calling process is not that of the creator
378 and the process was not privileged (Linux: did not have the
382 Or (in kernels before 2.6.9),
386 was specified, but the process was not privileged
387 (Linux: did not have the
390 (Since Linux 2.6.9, this error can also occur if the
392 is 0 and the caller is not privileged.)
394 POSIX.1-2001, POSIX.1-2008, SVr4.
395 .\" SVr4 documents additional error conditions EINVAL,
396 .\" ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents
397 .\" an EIDRM error condition.
403 isn't required on Linux or by any version of POSIX.
405 some old implementations required the inclusion of these header files,
406 and the SVID also documented their inclusion.
407 Applications intended to be portable to such old systems may need
408 to include these header files.
409 .\" Like Linux, the FreeBSD man pages still document
410 .\" the inclusion of these header files.
417 operations are used by the
419 program to provide information on allocated resources.
420 In the future, these may modified or moved to a
422 filesystem interface.
424 Linux permits a process to attach
426 a shared memory segment that has already been marked for deletion
428 .IR shmctl(IPC_RMID) .
429 This feature is not available on other UNIX implementations;
430 portable applications should avoid relying on it.
432 Various fields in a \fIstruct shmid_ds\fP were typed as
438 To take advantage of this,
439 a recompilation under glibc-2.1.91 or later should suffice.
440 (The kernel distinguishes old and new calls by an
449 .BR capabilities (7),