| blob | 6acc0b7871437f3185a940091b78a5978ea6ed1f |
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>
4 .\"
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.
9 .\"
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.
14 .\"
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
21 .\" professionally.
22 .\"
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
25 .\" %%%LICENSE_END
26 .\"
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.
45 .\"
46 .TH SHMCTL 2 2020-12-21 "Linux" "Linux Programmer's Manual"
47 .SH NAME
48 shmctl \- System V shared memory control
49 .SH SYNOPSIS
50 .nf
51 .ad l
52 .B #include <sys/ipc.h>
53 .B #include <sys/shm.h>
54 .PP
55 .BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf );
56 .ad b
57 .fi
58 .SH DESCRIPTION
59 .BR shmctl ()
60 performs the control operation specified by
61 .I cmd
62 on the System\ V shared memory segment whose identifier is given in
63 .IR shmid .
64 .PP
65 The
66 .I buf
67 argument is a pointer to a \fIshmid_ds\fP structure,
68 defined in \fI<sys/shm.h>\fP as follows:
69 .PP
70 .in +4n
71 .EX
72 struct shmid_ds {
73 struct ipc_perm shm_perm; /* Ownership and permissions */
74 size_t shm_segsz; /* Size of segment (bytes) */
75 time_t shm_atime; /* Last attach time */
76 time_t shm_dtime; /* Last detach time */
77 time_t shm_ctime; /* Creation time/time of last
78 modification via shmctl() */
79 pid_t shm_cpid; /* PID of creator */
80 pid_t shm_lpid; /* PID of last shmat(2)/shmdt(2) */
81 shmatt_t shm_nattch; /* No. of current attaches */
82 ...
83 };
84 .EE
85 .in
86 .PP
87 The fields of the
88 .I shmid_ds
89 structure are as follows:
90 .TP 12
91 .I shm_perm
92 This is an
93 .I ipc_perm
94 structure (see below) that specifies the access permissions
95 on the shared memory segment.
96 .TP
97 .I shm_segsz
98 Size in bytes of the shared memory segment.
99 .TP
100 .I shm_atime
101 Time of the last
102 .BR shmat (2)
103 system call that attached this segment.
104 .TP
105 .I shm_dtime
106 Time of the last
107 .BR shmdt (2)
108 system call that detached tgis segment.
109 .TP
110 .I shm_ctime
111 Time of creation of segment or time of the last
112 .BR shmctl ()
113 .BR IPC_SET
114 operation.
115 .TP
116 .I shm_cpid
117 ID of the process that created the shared memory segment.
118 .TP
119 .I shm_lpid
120 ID of the last process that executed a
121 .BR shmat (2)
122 or
123 .BR shmdt (2)
124 system call on this segment.
125 .TP
126 .I shm_nattch
127 Number of processes that have this segment attached.
128 .PP
129 The
130 .I ipc_perm
131 structure is defined as follows
132 (the highlighted fields are settable using
133 .BR IPC_SET ):
134 .PP
135 .in +4n
136 .EX
137 struct ipc_perm {
138 key_t __key; /* Key supplied to shmget(2) */
139 uid_t \fBuid\fP; /* Effective UID of owner */
140 gid_t \fBgid\fP; /* Effective GID of owner */
141 uid_t cuid; /* Effective UID of creator */
142 gid_t cgid; /* Effective GID of creator */
143 unsigned short \fBmode\fP; /* \fBPermissions\fP + SHM_DEST and
144 SHM_LOCKED flags */
145 unsigned short __seq; /* Sequence number */
146 };
147 .EE
148 .in
149 .PP
150 The least significant 9 bits of the
151 .I mode
152 field of the
153 .I ipc_perm
154 structure define the access permissions for the shared memory segment.
155 The permission bits are as follows:
156 .TS
157 l l.
158 0400 Read by user
159 0200 Write by user
160 0040 Read by group
161 0020 Write by group
162 0004 Read by others
163 0002 Write by others
164 .TE
165 .PP
166 Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
167 (It is not necessary to have execute permission on a segment
168 in order to perform a
169 .BR shmat (2)
170 call with the
171 .B SHM_EXEC
172 flag.)
173 .PP
174 Valid values for
175 .I cmd
176 are:
177 .TP
178 .B IPC_STAT
179 Copy information from the kernel data structure associated with
180 .I shmid
181 into the
182 .I shmid_ds
183 structure pointed to by \fIbuf\fP.
184 The caller must have read permission on the
185 shared memory segment.
186 .TP
187 .B IPC_SET
188 Write the values of some members of the
189 .I shmid_ds
190 structure pointed to by
191 .I buf
192 to the kernel data structure associated with this shared memory segment,
193 updating also its
194 .I shm_ctime
195 member.
196 .IP
197 The following fields are updated:
198 \fIshm_perm.uid\fP, \fIshm_perm.gid\fP,
199 and (the least significant 9 bits of) \fIshm_perm.mode\fP.
200 .IP
201 The effective UID of the calling process must match the owner
202 .RI ( shm_perm.uid )
203 or creator
204 .RI ( shm_perm.cuid )
205 of the shared memory segment, or the caller must be privileged.
206 .TP
207 .B IPC_RMID
208 Mark the segment to be destroyed.
209 The segment will actually be destroyed
210 only after the last process detaches it (i.e., when the
211 .I shm_nattch
212 member of the associated structure
213 .I shmid_ds
214 is zero).
215 The caller must be the owner or creator of the segment, or be privileged.
216 The
217 .I buf
218 argument is ignored.
219 .IP
220 If a segment has been marked for destruction, then the (nonstandard)
221 .B SHM_DEST
222 flag of the
223 .I shm_perm.mode
224 field in the associated data structure retrieved by
225 .B IPC_STAT
226 will be set.
227 .IP
228 The caller \fImust\fP ensure that a segment is eventually destroyed;
229 otherwise its pages that were faulted in will remain in memory or swap.
230 .IP
231 See also the description of
232 .I /proc/sys/kernel/shm_rmid_forced
233 in
234 .BR proc (5).
235 .TP
236 .BR IPC_INFO " (Linux-specific)"
237 Return information about system-wide shared memory limits and
238 parameters in the structure pointed to by
239 .IR buf .
240 This structure is of type
241 .I shminfo
242 (thus, a cast is required),
243 defined in
244 .I <sys/shm.h>
245 if the
246 .B _GNU_SOURCE
247 feature test macro is defined:
248 .IP
249 .in +4n
250 .EX
251 struct shminfo {
252 unsigned long shmmax; /* Maximum segment size */
253 unsigned long shmmin; /* Minimum segment size;
254 always 1 */
255 unsigned long shmmni; /* Maximum number of segments */
256 unsigned long shmseg; /* Maximum number of segments
257 that a process can attach;
258 unused within kernel */
259 unsigned long shmall; /* Maximum number of pages of
260 shared memory, system\-wide */
261 };
262 .EE
263 .in
264 .IP
265 The
266 .IR shmmni ,
267 .IR shmmax ,
268 and
269 .I shmall
270 settings can be changed via
271 .I /proc
272 files of the same name; see
273 .BR proc (5)
274 for details.
275 .TP
276 .BR SHM_INFO " (Linux-specific)"
277 Return a
278 .I shm_info
279 structure whose fields contain information
280 about system resources consumed by shared memory.
281 This structure is defined in
282 .I <sys/shm.h>
283 if the
284 .B _GNU_SOURCE
285 feature test macro is defined:
286 .IP
287 .in +4n
288 .EX
289 struct shm_info {
290 int used_ids; /* # of currently existing
291 segments */
292 unsigned long shm_tot; /* Total number of shared
293 memory pages */
294 unsigned long shm_rss; /* # of resident shared
295 memory pages */
296 unsigned long shm_swp; /* # of swapped shared
297 memory pages */
298 unsigned long swap_attempts;
299 /* Unused since Linux 2.4 */
300 unsigned long swap_successes;
301 /* Unused since Linux 2.4 */
302 };
303 .EE
304 .in
305 .TP
306 .BR SHM_STAT " (Linux-specific)"
307 Return a
308 .I shmid_ds
309 structure as for
310 .BR IPC_STAT .
311 However, the
312 .I shmid
313 argument is not a segment identifier, but instead an index into
314 the kernel's internal array that maintains information about
315 all shared memory segments on the system.
316 .TP
317 .BR SHM_STAT_ANY " (Linux-specific, since Linux 4.17)"
318 Return a
319 .I shmid_ds
320 structure as for
321 .BR SHM_STAT .
322 However,
323 .I shm_perm.mode
324 is not checked for read access for
325 .IR shmid ,
326 meaning that any user can employ this operation (just as any user may read
327 .IR /proc/sysvipc/shm
328 to obtain the same information).
329 .PP
330 The caller can prevent or allow swapping of a shared
331 memory segment with the following \fIcmd\fP values:
332 .TP
333 .BR SHM_LOCK " (Linux-specific)"
334 Prevent swapping of the shared memory segment.
335 The caller must fault in
336 any pages that are required to be present after locking is enabled.
337 If a segment has been locked, then the (nonstandard)
338 .B SHM_LOCKED
339 flag of the
340 .I shm_perm.mode
341 field in the associated data structure retrieved by
342 .B IPC_STAT
343 will be set.
344 .TP
345 .BR SHM_UNLOCK " (Linux-specific)"
346 Unlock the segment, allowing it to be swapped out.
347 .PP
348 In kernels before 2.6.10, only a privileged process
349 could employ
350 .B SHM_LOCK
351 and
352 .BR SHM_UNLOCK .
353 Since kernel 2.6.10, an unprivileged process can employ these operations
354 if its effective UID matches the owner or creator UID of the segment, and
355 (for
356 .BR SHM_LOCK )
357 the amount of memory to be locked falls within the
358 .B RLIMIT_MEMLOCK
359 resource limit (see
360 .BR setrlimit (2)).
361 .\" There was some weirdness in 2.6.9: SHM_LOCK and SHM_UNLOCK could
362 .\" be applied to a segment, regardless of ownership of the segment.
363 .\" This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed
364 .\" in 2.6.10. MTK, May 2005
365 .SH RETURN VALUE
366 A successful
367 .B IPC_INFO
368 or
369 .B SHM_INFO
370 operation returns the index of the highest used entry in the
371 kernel's internal array recording information about all
372 shared memory segments.
373 (This information can be used with repeated
374 .B SHM_STAT
375 or
376 .B SHM_STAT_ANY
377 operations to obtain information about all shared memory segments
378 on the system.)
379 A successful
380 .B SHM_STAT
381 operation returns the identifier of the shared memory segment
382 whose index was given in
383 .IR shmid .
384 Other operations return 0 on success.
385 .PP
386 On error, \-1 is returned, and
387 .I errno
388 is set to indicate the error.
389 .SH ERRORS
390 .TP
391 .B EACCES
392 \fBIPC_STAT\fP or \fBSHM_STAT\fP is requested and
393 \fIshm_perm.mode\fP does not allow read access for
394 .IR shmid ,
395 and the calling process does not have the
396 .B CAP_IPC_OWNER
397 capability in the user namespace that governs its IPC namespace.
398 .TP
399 .B EFAULT
400 The argument
401 .I cmd
402 has value
403 .B IPC_SET
404 or
405 .B IPC_STAT
406 but the address pointed to by
407 .I buf
408 isn't accessible.
409 .TP
410 .B EIDRM
411 \fIshmid\fP points to a removed identifier.
412 .TP
413 .B EINVAL
414 \fIshmid\fP is not a valid identifier, or \fIcmd\fP
415 is not a valid command.
416 Or: for a
417 .B SHM_STAT
418 or
419 .B SHM_STAT_ANY
420 operation, the index value specified in
421 .I shmid
422 referred to an array slot that is currently unused.
423 .TP
424 .B ENOMEM
425 (In kernels since 2.6.9),
426 .B SHM_LOCK
427 was specified and the size of the to-be-locked segment would mean
428 that the total bytes in locked shared memory segments would exceed
429 the limit for the real user ID of the calling process.
430 This limit is defined by the
431 .B RLIMIT_MEMLOCK
432 soft resource limit (see
433 .BR setrlimit (2)).
434 .TP
435 .B EOVERFLOW
436 \fBIPC_STAT\fP is attempted, and the GID or UID value
437 is too large to be stored in the structure pointed to by
438 .IR buf .
439 .TP
440 .B EPERM
441 \fBIPC_SET\fP or \fBIPC_RMID\fP is attempted, and the
442 effective user ID of the calling process is not that of the creator
443 (found in
444 .IR shm_perm.cuid ),
445 or the owner
446 (found in
447 .IR shm_perm.uid ),
448 and the process was not privileged (Linux: did not have the
449 .B CAP_SYS_ADMIN
450 capability).
451 .IP
452 Or (in kernels before 2.6.9),
453 .B SHM_LOCK
454 or
455 .B SHM_UNLOCK
456 was specified, but the process was not privileged
457 (Linux: did not have the
458 .B CAP_IPC_LOCK
459 capability).
460 (Since Linux 2.6.9, this error can also occur if the
461 .B RLIMIT_MEMLOCK
462 is 0 and the caller is not privileged.)
463 .SH CONFORMING TO
464 POSIX.1-2001, POSIX.1-2008, SVr4.
465 .\" SVr4 documents additional error conditions EINVAL,
466 .\" ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents
467 .\" an EIDRM error condition.
468 .SH NOTES
469 The inclusion of
470 .I <sys/ipc.h>
471 isn't required on Linux or by any version of POSIX.
472 However,
473 some old implementations required the inclusion of this header file,
474 and the SVID also documented its inclusion.
475 Applications intended to be portable to such old systems may need
476 to include this header file.
477 .\" Like Linux, the FreeBSD man pages still document
478 .\" the inclusion of this header file.
479 .PP
480 The
481 .BR IPC_INFO ,
482 .BR SHM_STAT ,
483 and
484 .B SHM_INFO
485 operations are used by the
486 .BR ipcs (1)
487 program to provide information on allocated resources.
488 In the future, these may modified or moved to a
489 .I /proc
490 filesystem interface.
491 .PP
492 Linux permits a process to attach
493 .RB ( shmat (2))
494 a shared memory segment that has already been marked for deletion
495 using
496 .IR shmctl(IPC_RMID) .
497 This feature is not available on other UNIX implementations;
498 portable applications should avoid relying on it.
499 .PP
500 Various fields in a \fIstruct shmid_ds\fP were typed as
501 .I short
502 under Linux 2.2
503 and have become
504 .I long
505 under Linux 2.4.
506 To take advantage of this,
507 a recompilation under glibc-2.1.91 or later should suffice.
508 (The kernel distinguishes old and new calls by an
509 .B IPC_64
510 flag in
511 .IR cmd .)
512 .SH SEE ALSO
513 .BR mlock (2),
514 .BR setrlimit (2),
515 .BR shmget (2),
516 .BR shmop (2),
517 .BR capabilities (7),
518 .BR sysvipc (7)