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