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