Debian Codegraph @

upstream/debian-unstable/man2/shmctl.2

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