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 2021-03-22 "Linux" "Linux Programmer's Manual"
48 shmctl \- System V shared memory control
52 .B #include <sys/shm.h>
54 .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; /* Creation time/time of last
77 modification via shmctl() */
78 pid_t shm_cpid; /* PID of creator */
79 pid_t shm_lpid; /* PID of last shmat(2)/shmdt(2) */
80 shmatt_t shm_nattch; /* No. of current attaches */
88 structure are as follows:
93 structure (see below) that specifies the access permissions
94 on the shared memory segment.
97 Size in bytes of the shared memory segment.
102 system call that attached this segment.
107 system call that detached tgis segment.
110 Time of creation of segment or time of the last
116 ID of the process that created the shared memory segment.
119 ID of the last process that executed a
123 system call on this segment.
126 Number of processes that have this segment attached.
130 structure is defined as follows
131 (the highlighted fields are settable using
137 key_t __key; /* Key supplied to shmget(2) */
138 uid_t \fBuid\fP; /* Effective UID of owner */
139 gid_t \fBgid\fP; /* Effective GID of owner */
140 uid_t cuid; /* Effective UID of creator */
141 gid_t cgid; /* Effective GID of creator */
142 unsigned short \fBmode\fP; /* \fBPermissions\fP + SHM_DEST and
144 unsigned short __seq; /* Sequence number */
149 The least significant 9 bits of the
153 structure define the access permissions for the shared memory segment.
154 The permission bits are as follows:
165 Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
166 (It is not necessary to have execute permission on a segment
167 in order to perform a
178 Copy information from the kernel data structure associated with
182 structure pointed to by \fIbuf\fP.
183 The caller must have read permission on the
184 shared memory segment.
187 Write the values of some members of the
189 structure pointed to by
191 to the kernel data structure associated with this shared memory segment,
196 The following fields are updated:
197 \fIshm_perm.uid\fP, \fIshm_perm.gid\fP,
198 and (the least significant 9 bits of) \fIshm_perm.mode\fP.
200 The effective UID of the calling process must match the owner
203 .RI ( shm_perm.cuid )
204 of the shared memory segment, or the caller must be privileged.
207 Mark the segment to be destroyed.
208 The segment will actually be destroyed
209 only after the last process detaches it (i.e., when the
211 member of the associated structure
214 The caller must be the owner or creator of the segment, or be privileged.
219 If a segment has been marked for destruction, then the (nonstandard)
223 field in the associated data structure retrieved by
227 The caller \fImust\fP ensure that a segment is eventually destroyed;
228 otherwise its pages that were faulted in will remain in memory or swap.
230 See also the description of
231 .I /proc/sys/kernel/shm_rmid_forced
235 .BR IPC_INFO " (Linux-specific)"
236 Return information about system-wide shared memory limits and
237 parameters in the structure pointed to by
239 This structure is of type
241 (thus, a cast is required),
246 feature test macro is defined:
251 unsigned long shmmax; /* Maximum segment size */
252 unsigned long shmmin; /* Minimum segment size;
254 unsigned long shmmni; /* Maximum number of segments */
255 unsigned long shmseg; /* Maximum number of segments
256 that a process can attach;
257 unused within kernel */
258 unsigned long shmall; /* Maximum number of pages of
259 shared memory, system\-wide */
269 settings can be changed via
271 files of the same name; see
275 .BR SHM_INFO " (Linux-specific)"
278 structure whose fields contain information
279 about system resources consumed by shared memory.
280 This structure is defined in
284 feature test macro is defined:
289 int used_ids; /* # of currently existing
291 unsigned long shm_tot; /* Total number of shared
293 unsigned long shm_rss; /* # of resident shared
295 unsigned long shm_swp; /* # of swapped shared
297 unsigned long swap_attempts;
298 /* Unused since Linux 2.4 */
299 unsigned long swap_successes;
300 /* Unused since Linux 2.4 */
305 .BR SHM_STAT " (Linux-specific)"
312 argument is not a segment identifier, but instead an index into
313 the kernel's internal array that maintains information about
314 all shared memory segments on the system.
316 .BR SHM_STAT_ANY " (Linux-specific, since Linux 4.17)"
323 is not checked for read access for
325 meaning that any user can employ this operation (just as any user may read
326 .IR /proc/sysvipc/shm
327 to obtain the same information).
329 The caller can prevent or allow swapping of a shared
330 memory segment with the following \fIcmd\fP values:
332 .BR SHM_LOCK " (Linux-specific)"
333 Prevent swapping of the shared memory segment.
334 The caller must fault in
335 any pages that are required to be present after locking is enabled.
336 If a segment has been locked, then the (nonstandard)
340 field in the associated data structure retrieved by
344 .BR SHM_UNLOCK " (Linux-specific)"
345 Unlock the segment, allowing it to be swapped out.
347 In kernels before 2.6.10, only a privileged process
352 Since kernel 2.6.10, an unprivileged process can employ these operations
353 if its effective UID matches the owner or creator UID of the segment, and
356 the amount of memory to be locked falls within the
360 .\" There was some weirdness in 2.6.9: SHM_LOCK and SHM_UNLOCK could
361 .\" be applied to a segment, regardless of ownership of the segment.
362 .\" This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed
363 .\" in 2.6.10. MTK, May 2005
369 operation returns the index of the highest used entry in the
370 kernel's internal array recording information about all
371 shared memory segments.
372 (This information can be used with repeated
376 operations to obtain information about all shared memory segments
380 operation returns the identifier of the shared memory segment
381 whose index was given in
383 Other operations return 0 on success.
385 On error, \-1 is returned, and
387 is set to indicate the error.
391 \fBIPC_STAT\fP or \fBSHM_STAT\fP is requested and
392 \fIshm_perm.mode\fP does not allow read access for
394 and the calling process does not have the
396 capability in the user namespace that governs its IPC namespace.
405 but the address pointed to by
410 \fIshmid\fP points to a removed identifier.
413 \fIshmid\fP is not a valid identifier, or \fIcmd\fP
414 is not a valid command.
419 operation, the index value specified in
421 referred to an array slot that is currently unused.
424 (In kernels since 2.6.9),
426 was specified and the size of the to-be-locked segment would mean
427 that the total bytes in locked shared memory segments would exceed
428 the limit for the real user ID of the calling process.
429 This limit is defined by the
431 soft resource limit (see
435 \fBIPC_STAT\fP is attempted, and the GID or UID value
436 is too large to be stored in the structure pointed to by
440 \fBIPC_SET\fP or \fBIPC_RMID\fP is attempted, and the
441 effective user ID of the calling process is not that of the creator
447 and the process was not privileged (Linux: did not have the
451 Or (in kernels before 2.6.9),
455 was specified, but the process was not privileged
456 (Linux: did not have the
459 (Since Linux 2.6.9, this error can also occur if the
461 is 0 and the caller is not privileged.)
463 POSIX.1-2001, POSIX.1-2008, SVr4.
464 .\" SVr4 documents additional error conditions EINVAL,
465 .\" ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents
466 .\" an EIDRM error condition.
473 operations are used by the
475 program to provide information on allocated resources.
476 In the future, these may modified or moved to a
478 filesystem interface.
480 Linux permits a process to attach
482 a shared memory segment that has already been marked for deletion
484 .IR shmctl(IPC_RMID) .
485 This feature is not available on other UNIX implementations;
486 portable applications should avoid relying on it.
488 Various fields in a \fIstruct shmid_ds\fP were typed as
494 To take advantage of this,
495 a recompilation under glibc-2.1.91 or later should suffice.
496 (The kernel distinguishes old and new calls by an
505 .BR capabilities (7),