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