Debian Codegraph @

upstream/debian-trixie/man2/shmctl.2

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