]>
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. |
fea681da | 44 | .\" |
0a10242a | 45 | .TH SHMCTL 2 2014-02-07 "Linux" "Linux Programmer's Manual" |
fea681da | 46 | .SH NAME |
47f065d6 | 47 | shmctl \- System V shared memory control |
fea681da MK |
48 | .SH SYNOPSIS |
49 | .ad l | |
50 | .B #include <sys/ipc.h> | |
d314dbfd | 51 | .br |
fea681da MK |
52 | .B #include <sys/shm.h> |
53 | .sp | |
54 | .BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf ); | |
55 | .ad b | |
56 | .SH DESCRIPTION | |
540036b2 | 57 | .BR shmctl () |
de84c942 MK |
58 | performs the control operation specified by |
59 | .I cmd | |
47f065d6 | 60 | on the System V shared memory segment whose identifier is given in |
de84c942 | 61 | .IR shmid . |
9907019a MK |
62 | .PP |
63 | The | |
64 | .I buf | |
65 | argument is a pointer to a \fIshmid_ds\fP structure, | |
c84371c6 | 66 | defined in \fI<sys/shm.h>\fP as follows: |
fea681da MK |
67 | .PP |
68 | .in +4n | |
69 | .nf | |
70 | struct shmid_ds { | |
9907019a MK |
71 | struct ipc_perm shm_perm; /* Ownership and permissions */ |
72 | size_t shm_segsz; /* Size of segment (bytes) */ | |
73 | time_t shm_atime; /* Last attach time */ | |
74 | time_t shm_dtime; /* Last detach time */ | |
75 | time_t shm_ctime; /* Last change time */ | |
76 | pid_t shm_cpid; /* PID of creator */ | |
0bfa087b | 77 | pid_t shm_lpid; /* PID of last shmat(2)/shmdt(2) */ |
9907019a | 78 | shmatt_t shm_nattch; /* No. of current attaches */ |
fea681da MK |
79 | ... |
80 | }; | |
81 | .fi | |
088a639b | 82 | .in |
fea681da | 83 | .PP |
9907019a MK |
84 | The |
85 | .I ipc_perm | |
548be2a6 | 86 | structure is defined as follows |
9907019a MK |
87 | (the highlighted fields are settable using |
88 | .BR IPC_SET ): | |
fea681da MK |
89 | .PP |
90 | .in +4n | |
91 | .nf | |
92 | struct ipc_perm { | |
2d2892fc | 93 | key_t __key; /* Key supplied to shmget(2) */ |
6edbac01 MK |
94 | uid_t \fBuid\fP; /* Effective UID of owner */ |
95 | gid_t \fBgid\fP; /* Effective GID of owner */ | |
96 | uid_t cuid; /* Effective UID of creator */ | |
97 | gid_t cgid; /* Effective GID of creator */ | |
98 | unsigned short \fBmode\fP; /* \fBPermissions\fP + SHM_DEST and | |
99 | SHM_LOCKED flags */ | |
2d2892fc | 100 | unsigned short __seq; /* Sequence number */ |
fea681da MK |
101 | }; |
102 | .fi | |
088a639b | 103 | .in |
fea681da | 104 | .PP |
9907019a MK |
105 | Valid values for |
106 | .I cmd | |
107 | are: | |
fea681da | 108 | .br |
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 MK |
138 | Mark the segment to be destroyed. |
139 | The segment will only actually be destroyed | |
140 | 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)" |
c13182ef | 167 | Returns 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: | |
79dded64 | 178 | .nf |
088a639b | 179 | .in +4n |
79dded64 MK |
180 | |
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 MK |
191 | }; |
192 | ||
088a639b | 193 | .in |
79dded64 | 194 | .fi |
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)" |
79dded64 MK |
207 | Returns a |
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: | |
79dded64 | 216 | .nf |
088a639b | 217 | .in +4n |
79dded64 MK |
218 | |
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 | }; |
088a639b | 233 | .in |
79dded64 MK |
234 | .fi |
235 | .TP | |
8382f16d | 236 | .BR SHM_STAT " (Linux-specific)" |
c13182ef MK |
237 | Returns a |
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. | |
2202881e MK |
246 | .PP |
247 | The caller can prevent or allow swapping of a shared | |
9907019a | 248 | memory segment with the following \fIcmd\fP values: |
fea681da | 249 | .br |
9fcbe835 | 250 | .TP 10 |
8382f16d | 251 | .BR SHM_LOCK " (Linux-specific)" |
c13182ef MK |
252 | Prevent swapping of the shared memory segment. |
253 | The caller must fault in | |
fea681da | 254 | any pages that are required to be present after locking is enabled. |
c8f2dd47 | 255 | If a segment has been locked, then the (nonstandard) |
0daa9e92 | 256 | .B SHM_LOCKED |
9907019a MK |
257 | flag of the |
258 | .I shm_perm.mode | |
259 | field in the associated data structure retrieved by | |
260 | .B IPC_STAT | |
261 | will be set. | |
fea681da | 262 | .TP |
8382f16d | 263 | .BR SHM_UNLOCK " (Linux-specific)" |
9907019a | 264 | Unlock the segment, allowing it to be swapped out. |
fea681da | 265 | .PP |
2202881e MK |
266 | In kernels before 2.6.10, only a privileged process |
267 | could employ | |
268 | .B SHM_LOCK | |
fea681da | 269 | and |
2202881e | 270 | .BR SHM_UNLOCK . |
c13182ef | 271 | Since kernel 2.6.10, an unprivileged process can employ these operations |
2202881e MK |
272 | if its effective UID matches the owner or creator UID of the segment, and |
273 | (for | |
274 | .BR SHM_LOCK ) | |
275 | the amount of memory to be locked falls within the | |
0daa9e92 | 276 | .B RLIMIT_MEMLOCK |
2202881e MK |
277 | resource limit (see |
278 | .BR setrlimit (2)). | |
c13182ef | 279 | .\" There was some weirdness in 2.6.9: SHM_LOCK and SHM_UNLOCK could |
2202881e | 280 | .\" be applied to a segment, regardless of ownership of the segment. |
c13182ef | 281 | .\" This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed |
2202881e | 282 | .\" in 2.6.10. MTK, May 2005 |
47297adb | 283 | .SH RETURN VALUE |
79dded64 MK |
284 | A successful |
285 | .B IPC_INFO | |
c13182ef | 286 | or |
79dded64 MK |
287 | .B SHM_INFO |
288 | operation returns the index of the highest used entry in the | |
289 | kernel's internal array recording information about all | |
290 | shared memory segments. | |
291 | (This information can be used with repeated | |
c13182ef MK |
292 | .B SHM_STAT |
293 | operations to obtain information about all shared memory segments | |
79dded64 MK |
294 | on the system.) |
295 | A successful | |
296 | .B SHM_STAT | |
c13182ef | 297 | operation returns the identifier of the shared memory segment |
79dded64 MK |
298 | whose index was given in |
299 | .IR shmid . | |
300 | Other operations return 0 on success. | |
301 | ||
fea681da MK |
302 | On error, \-1 is returned, and |
303 | .I errno | |
304 | is set appropriately. | |
305 | .SH ERRORS | |
89b3c6b8 | 306 | .TP |
fea681da MK |
307 | .B EACCES |
308 | \fBIPC_STAT\fP or \fBSHM_STAT\fP is requested and | |
75ced2e8 | 309 | \fIshm_perm.mode\fP does not allow read access for |
fea681da MK |
310 | .IR shmid , |
311 | and the calling process does not have the | |
0daa9e92 | 312 | .B CAP_IPC_OWNER |
fea681da MK |
313 | capability. |
314 | .TP | |
315 | .B EFAULT | |
316 | The argument | |
317 | .I cmd | |
318 | has value | |
319 | .B IPC_SET | |
320 | or | |
321 | .B IPC_STAT | |
322 | but the address pointed to by | |
323 | .I buf | |
324 | isn't accessible. | |
325 | .TP | |
326 | .B EIDRM | |
327 | \fIshmid\fP points to a removed identifier. | |
328 | .TP | |
329 | .B EINVAL | |
330 | \fIshmid\fP is not a valid identifier, or \fIcmd\fP | |
331 | is not a valid command. | |
79dded64 MK |
332 | Or: for a |
333 | .B SHM_STAT | |
c13182ef | 334 | operation, the index value specified in |
79dded64 MK |
335 | .I shmid |
336 | referred to an array slot that is currently unused. | |
fea681da | 337 | .TP |
583d5fd3 MK |
338 | .B ENOMEM |
339 | (In kernels since 2.6.9), | |
340 | .B SHM_LOCK | |
c13182ef | 341 | was specified and the size of the to-be-locked segment would mean |
583d5fd3 MK |
342 | that the total bytes in locked shared memory segments would exceed |
343 | the limit for the real user ID of the calling process. | |
344 | This limit is defined by the | |
0daa9e92 | 345 | .B RLIMIT_MEMLOCK |
583d5fd3 MK |
346 | soft resource limit (see |
347 | .BR setrlimit (2)). | |
348 | .TP | |
fea681da | 349 | .B EOVERFLOW |
e75a4542 | 350 | \fBIPC_STAT\fP is attempted, and the GID or UID value |
fea681da | 351 | is too large to be stored in the structure pointed to by |
9907019a | 352 | .IR buf . |
fea681da MK |
353 | .TP |
354 | .B EPERM | |
355 | \fBIPC_SET\fP or \fBIPC_RMID\fP is attempted, and the | |
356 | effective user ID of the calling process is not that of the creator | |
357 | (found in | |
358 | .IR shm_perm.cuid ), | |
359 | or the owner | |
360 | (found in | |
361 | .IR shm_perm.uid ), | |
362 | and the process was not privileged (Linux: did not have the | |
363 | .B CAP_SYS_ADMIN | |
364 | capability). | |
365 | ||
583d5fd3 | 366 | Or (in kernels before 2.6.9), |
fea681da MK |
367 | .B SHM_LOCK |
368 | or | |
369 | .B SHM_UNLOCK | |
370 | was specified, but the process was not privileged | |
371 | (Linux: did not have the | |
372 | .B CAP_IPC_LOCK | |
373 | capability). | |
583d5fd3 | 374 | (Since Linux 2.6.9, this error can also occur if the |
0daa9e92 | 375 | .B RLIMIT_MEMLOCK |
583d5fd3 | 376 | is 0 and the caller is not privileged.) |
47297adb | 377 | .SH CONFORMING TO |
a1d5f77c MK |
378 | SVr4, POSIX.1-2001. |
379 | .\" SVr4 documents additional error conditions EINVAL, | |
380 | .\" ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents | |
381 | .\" an EIDRM error condition. | |
75ced2e8 | 382 | .SH NOTES |
f6652463 MK |
383 | The inclusion of |
384 | .I <sys/types.h> | |
385 | and | |
386 | .I <sys/ipc.h> | |
387 | isn't required on Linux or by any version of POSIX. | |
388 | However, | |
389 | some old implementations required the inclusion of these header files, | |
390 | and the SVID also documented their inclusion. | |
391 | Applications intended to be portable to such old systems may need | |
392 | to include these header files. | |
393 | .\" Like Linux, the FreeBSD man pages still document | |
394 | .\" the inclusion of these header files. | |
395 | ||
79dded64 MK |
396 | The |
397 | .BR IPC_INFO , | |
0daa9e92 | 398 | .B SHM_STAT |
79dded64 MK |
399 | and |
400 | .B SHM_INFO | |
401 | operations are used by the | |
81a8f8e7 | 402 | .BR ipcs (1) |
79dded64 | 403 | program to provide information on allocated resources. |
2177a367 | 404 | In the future, these may modified or moved to a |
282c1a35 MK |
405 | .I /proc |
406 | filesystem interface. | |
79dded64 | 407 | |
c13182ef | 408 | Linux permits a process to attach |
0bfa087b | 409 | .RB ( shmat (2)) |
75ced2e8 MK |
410 | a shared memory segment that has already been marked for deletion |
411 | using | |
412 | .IR shmctl(IPC_RMID) . | |
008f1ecc | 413 | This feature is not available on other UNIX implementations; |
75ced2e8 MK |
414 | portable applications should avoid relying on it. |
415 | ||
e3e25559 MK |
416 | Various fields in a \fIstruct shmid_ds\fP were typed as |
417 | .I short | |
418 | under Linux 2.2 | |
419 | and have become | |
420 | .I long | |
421 | under Linux 2.4. | |
c13182ef | 422 | To take advantage of this, |
fea681da | 423 | a recompilation under glibc-2.1.91 or later should suffice. |
097585ed MK |
424 | (The kernel distinguishes old and new calls by an |
425 | .B IPC_64 | |
426 | flag in | |
fea681da | 427 | .IR cmd .) |
47297adb | 428 | .SH SEE ALSO |
9907019a | 429 | .BR mlock (2), |
583d5fd3 | 430 | .BR setrlimit (2), |
fea681da MK |
431 | .BR shmget (2), |
432 | .BR shmop (2), | |
1df962c8 MK |
433 | .BR capabilities (7), |
434 | .BR svipc (7) |