]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) |
c11b1abf | 2 | .\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
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. | |
c13182ef | 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. | |
c13182ef | 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. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond <esr@thyrsus.com> | |
27 | .\" Modified Sun Feb 18 01:59:29 2001 by Andries E. Brouwer <aeb@cwi.nl> | |
c11b1abf | 28 | .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 29 | .\" Added notes on CAP_IPC_OWNER requirement |
c11b1abf | 30 | .\" Modified, 17 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 31 | .\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID |
c11b1abf | 32 | .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
70d0e5ef MK |
33 | .\" Language and formatting clean-ups |
34 | .\" Added msqid_ds and ipc_perm structure definitions | |
f3021697 | 35 | .\" 2005-08-02, mtk: Added IPC_INFO, MSG_INFO, MSG_STAT descriptions |
d2ff4f86 | 36 | .\" 2018-03-20, dbueso: Added MSG_STAT_ANY description. |
fea681da | 37 | .\" |
9ba01802 | 38 | .TH MSGCTL 2 2019-03-06 "Linux" "Linux Programmer's Manual" |
fea681da | 39 | .SH NAME |
47f065d6 | 40 | msgctl \- System V message control operations |
fea681da MK |
41 | .SH SYNOPSIS |
42 | .nf | |
2fadbfb5 MK |
43 | .B #include <sys/types.h> |
44 | .B #include <sys/ipc.h> | |
45 | .B #include <sys/msg.h> | |
dbfe9c70 | 46 | .PP |
34e8ac03 | 47 | .BI "int msgctl(int " msqid ", int " cmd ", struct msqid_ds *" buf ); |
fea681da | 48 | .fi |
fea681da | 49 | .SH DESCRIPTION |
540036b2 | 50 | .BR msgctl () |
70d0e5ef | 51 | performs the control operation specified by |
fea681da | 52 | .I cmd |
efbfd7ec | 53 | on the System\ V message queue with identifier |
fea681da | 54 | .IR msqid . |
70d0e5ef MK |
55 | .PP |
56 | The | |
57 | .I msqid_ds | |
c84371c6 | 58 | data structure is defined in \fI<sys/msg.h>\fP as follows: |
e646a1ba | 59 | .PP |
70d0e5ef | 60 | .in +4n |
e646a1ba | 61 | .EX |
70d0e5ef | 62 | struct msqid_ds { |
c153f4a6 MK |
63 | struct ipc_perm msg_perm; /* Ownership and permissions */ |
64 | time_t msg_stime; /* Time of last msgsnd(2) */ | |
65 | time_t msg_rtime; /* Time of last msgrcv(2) */ | |
66 | time_t msg_ctime; /* Time of last change */ | |
67 | unsigned long __msg_cbytes; /* Current number of bytes in | |
c8f2dd47 | 68 | queue (nonstandard) */ |
c153f4a6 MK |
69 | msgqnum_t msg_qnum; /* Current number of messages |
70 | in queue */ | |
71 | msglen_t msg_qbytes; /* Maximum number of bytes | |
72 | allowed in queue */ | |
73 | pid_t msg_lspid; /* PID of last msgsnd(2) */ | |
74 | pid_t msg_lrpid; /* PID of last msgrcv(2) */ | |
70d0e5ef | 75 | }; |
b8302363 | 76 | .EE |
e646a1ba | 77 | .in |
70d0e5ef MK |
78 | .PP |
79 | The | |
80 | .I ipc_perm | |
548be2a6 | 81 | structure is defined as follows |
70d0e5ef MK |
82 | (the highlighted fields are settable using |
83 | .BR IPC_SET ): | |
84 | .PP | |
70d0e5ef | 85 | .in +4n |
b8302363 | 86 | .EX |
70d0e5ef | 87 | struct ipc_perm { |
b1018277 | 88 | key_t __key; /* Key supplied to msgget(2) */ |
a2a11a45 MK |
89 | uid_t \fBuid\fP; /* Effective UID of owner */ |
90 | gid_t \fBgid\fP; /* Effective GID of owner */ | |
91 | uid_t cuid; /* Effective UID of creator */ | |
92 | gid_t cgid; /* Effective GID of creator */ | |
93 | unsigned short \fBmode\fP; /* Permissions */ | |
116e7cd9 | 94 | unsigned short __seq; /* Sequence number */ |
70d0e5ef | 95 | }; |
b8302363 | 96 | .EE |
e646a1ba | 97 | .in |
70d0e5ef MK |
98 | .PP |
99 | Valid values for | |
fea681da MK |
100 | .I cmd |
101 | are: | |
102 | .TP | |
103 | .B IPC_STAT | |
70d0e5ef | 104 | Copy information from the kernel data structure associated with |
fea681da | 105 | .I msqid |
70d0e5ef MK |
106 | into the |
107 | .I msqid_ds | |
108 | structure pointed to by | |
fea681da MK |
109 | .IR buf . |
110 | The caller must have read permission on the message queue. | |
111 | .TP | |
112 | .B IPC_SET | |
113 | Write the values of some members of the | |
70d0e5ef | 114 | .I msqid_ds |
fea681da MK |
115 | structure pointed to by |
116 | .I buf | |
70d0e5ef MK |
117 | to the kernel data structure associated with this message queue, |
118 | updating also its | |
119 | .I msg_ctime | |
fea681da | 120 | member. |
c13182ef | 121 | The following members of the structure are updated: |
70d0e5ef MK |
122 | .IR msg_qbytes , |
123 | .IR msg_perm.uid , | |
124 | .IR msg_perm.gid , | |
125 | and (the least significant 9 bits of) | |
126 | .IR msg_perm.mode . | |
127 | The effective UID of the calling process must match the owner | |
fea681da | 128 | .RI ( msg_perm.uid ) |
c13182ef | 129 | or creator |
70d0e5ef MK |
130 | .RI ( msg_perm.cuid ) |
131 | of the message queue, or the caller must be privileged. | |
fea681da | 132 | Appropriate privilege (Linux: the |
1a83d697 | 133 | .B CAP_SYS_RESOURCE |
fea681da | 134 | capability) is required to raise the |
70d0e5ef | 135 | .I msg_qbytes |
fea681da MK |
136 | value beyond the system parameter |
137 | .BR MSGMNB . | |
138 | .TP | |
139 | .B IPC_RMID | |
70d0e5ef | 140 | Immediately remove the message queue, |
fea681da MK |
141 | awakening all waiting reader and writer processes (with an error |
142 | return and | |
70d0e5ef | 143 | .I errno |
fea681da MK |
144 | set to |
145 | .BR EIDRM ). | |
70d0e5ef | 146 | The calling process must have appropriate privileges |
499d62f2 | 147 | or its effective user ID must be either that of the creator or owner |
313dfec5 MK |
148 | of the message queue. |
149 | The third argument to | |
150 | .BR msgctl () | |
151 | is ignored in this case. | |
f3021697 | 152 | .TP |
8382f16d | 153 | .BR IPC_INFO " (Linux-specific)" |
97c4ec16 | 154 | Return information about system-wide message queue limits and |
f3021697 MK |
155 | parameters in the structure pointed to by |
156 | .IR buf . | |
157 | This structure is of type | |
0daa9e92 | 158 | .I msginfo |
f3021697 MK |
159 | (thus, a cast is required), |
160 | defined in | |
161 | .I <sys/msg.h> | |
682edefb | 162 | if the |
0daa9e92 | 163 | .B _GNU_SOURCE |
682edefb | 164 | feature test macro is defined: |
e646a1ba | 165 | .IP |
088a639b | 166 | .in +4n |
e646a1ba | 167 | .EX |
f3021697 | 168 | struct msginfo { |
767b89e8 MK |
169 | int msgpool; /* Size in kibibytes of buffer pool |
170 | used to hold message data; | |
171 | unused within kernel */ | |
172 | int msgmap; /* Maximum number of entries in message | |
173 | map; unused within kernel */ | |
174 | int msgmax; /* Maximum number of bytes that can be | |
f3021697 | 175 | written in a single message */ |
767b89e8 MK |
176 | int msgmnb; /* Maximum number of bytes that can be |
177 | written to queue; used to initialize | |
178 | msg_qbytes during queue creation | |
179 | (msgget(2)) */ | |
180 | int msgmni; /* Maximum number of message queues */ | |
181 | int msgssz; /* Message segment size; | |
182 | unused within kernel */ | |
183 | int msgtql; /* Maximum number of messages on all queues | |
184 | in system; unused within kernel */ | |
f3021697 | 185 | unsigned short int msgseg; |
767b89e8 MK |
186 | /* Maximum number of segments; |
187 | unused within kernel */ | |
f3021697 | 188 | }; |
e646a1ba | 189 | .EE |
088a639b | 190 | .in |
e646a1ba | 191 | .IP |
c13182ef | 192 | The |
f3021697 MK |
193 | .IR msgmni , |
194 | .IR msgmax , | |
195 | and | |
196 | .I msgmnb | |
197 | settings can be changed via | |
c13182ef | 198 | .I /proc |
f3021697 | 199 | files of the same name; see |
c13182ef | 200 | .BR proc (5) |
f3021697 MK |
201 | for details. |
202 | .TP | |
8382f16d | 203 | .BR MSG_INFO " (Linux-specific)" |
97c4ec16 | 204 | Return a |
f3021697 MK |
205 | .I msginfo |
206 | structure containing the same information as for | |
207 | .BR IPC_INFO , | |
c13182ef | 208 | except that the following fields are returned with information |
f3021697 MK |
209 | about system resources consumed by message queues: the |
210 | .I msgpool | |
c13182ef | 211 | field returns the number of message queues that currently exist |
f3021697 MK |
212 | on the system; the |
213 | .I msgmap | |
c13182ef | 214 | field returns the total number of messages in all queues |
f3021697 MK |
215 | on the system; and the |
216 | .I msgtql | |
c13182ef | 217 | field returns the total number of bytes in all messages |
f3021697 MK |
218 | in all queues on the system. |
219 | .TP | |
8382f16d | 220 | .BR MSG_STAT " (Linux-specific)" |
97c4ec16 | 221 | Return a |
c13182ef | 222 | .I msqid_ds |
f3021697 MK |
223 | structure as for |
224 | .BR IPC_STAT . | |
225 | However, the | |
5593795f | 226 | .I msqid |
f3021697 MK |
227 | argument is not a queue identifier, but instead an index into |
228 | the kernel's internal array that maintains information about | |
229 | all message queues on the system. | |
d2ff4f86 | 230 | .TP |
f7246c6d | 231 | .BR MSG_STAT_ANY " (Linux-specific, since Linux 4.17)" |
d2ff4f86 DB |
232 | Return a |
233 | .I msqid_ds | |
234 | structure as for | |
235 | .BR MSG_STAT . | |
c020b5a2 | 236 | However, |
d2ff4f86 DB |
237 | .I msg_perm.mode |
238 | is not checked for read access for | |
c020b5a2 MK |
239 | .IR msqid |
240 | meaning that any user can employ this operation (just as any user may read | |
241 | .IR /proc/sysvipc/msg | |
242 | to obtain the same information). | |
47297adb | 243 | .SH RETURN VALUE |
f3021697 MK |
244 | On success, |
245 | .BR IPC_STAT , | |
246 | .BR IPC_SET , | |
247 | and | |
0daa9e92 | 248 | .B IPC_RMID |
f3021697 MK |
249 | return 0. |
250 | A successful | |
251 | .B IPC_INFO | |
c13182ef | 252 | or |
f3021697 MK |
253 | .B MSG_INFO |
254 | operation returns the index of the highest used entry in the | |
255 | kernel's internal array recording information about all | |
256 | message queues. | |
257 | (This information can be used with repeated | |
14cbb25e MK |
258 | .B MSG_STAT |
259 | or | |
260 | .B MSG_STAT_ANY | |
f3021697 MK |
261 | operations to obtain information about all queues on the system.) |
262 | A successful | |
14cbb25e MK |
263 | .B MSG_STAT |
264 | or | |
265 | .B MSG_STAT_ANY | |
f3021697 MK |
266 | operation returns the identifier of the queue whose index was given in |
267 | .IR msqid . | |
efeece04 | 268 | .PP |
f3021697 | 269 | On error, \-1 is returned with |
70d0e5ef | 270 | .I errno |
fea681da MK |
271 | indicating the error. |
272 | .SH ERRORS | |
273 | On failure, | |
70d0e5ef | 274 | .I errno |
fea681da | 275 | is set to one of the following: |
89b3c6b8 | 276 | .TP |
fea681da MK |
277 | .B EACCES |
278 | The argument | |
279 | .I cmd | |
280 | is equal to | |
0daa9e92 | 281 | .B IPC_STAT |
fea681da MK |
282 | or |
283 | .BR MSG_STAT , | |
284 | but the calling process does not have read permission on the message queue | |
285 | .IR msqid , | |
286 | and does not have the | |
287 | .B CAP_IPC_OWNER | |
3294109d | 288 | capability in the user namespace that governs its IPC namespace. |
fea681da MK |
289 | .TP |
290 | .B EFAULT | |
291 | The argument | |
292 | .I cmd | |
293 | has the value | |
294 | .B IPC_SET | |
295 | or | |
296 | .BR IPC_STAT , | |
297 | but the address pointed to by | |
298 | .I buf | |
299 | isn't accessible. | |
300 | .TP | |
301 | .B EIDRM | |
302 | The message queue was removed. | |
303 | .TP | |
304 | .B EINVAL | |
305 | Invalid value for | |
306 | .I cmd | |
307 | or | |
308 | .IR msqid . | |
f3021697 MK |
309 | Or: for a |
310 | .B MSG_STAT | |
c13182ef | 311 | operation, the index value specified in |
f3021697 MK |
312 | .I msqid |
313 | referred to an array slot that is currently unused. | |
fea681da MK |
314 | .TP |
315 | .B EPERM | |
316 | The argument | |
317 | .I cmd | |
318 | has the value | |
319 | .B IPC_SET | |
320 | or | |
321 | .BR IPC_RMID , | |
322 | but the effective user ID of the calling process is not the creator | |
323 | (as found in | |
324 | .IR msg_perm.cuid ) | |
325 | or the owner | |
326 | (as found in | |
327 | .IR msg_perm.uid ) | |
328 | of the message queue, | |
754356db | 329 | and the caller is not privileged (Linux: does not have the |
fea681da MK |
330 | .B CAP_SYS_ADMIN |
331 | capability). | |
a77b0f28 MK |
332 | .TP |
333 | .B EPERM | |
334 | An attempt | |
335 | .RB ( IPC_SET ) | |
336 | was made to increase | |
337 | .I msg_qbytes | |
338 | beyond the system parameter | |
339 | .BR MSGMNB , | |
340 | but the caller is not privileged (Linux: does not have the | |
341 | .B CAP_SYS_RESOURCE | |
342 | capability). | |
47297adb | 343 | .SH CONFORMING TO |
5dd9b8a9 | 344 | POSIX.1-2001, POSIX.1-2008, SVr4. |
a1d5f77c | 345 | .\" SVID does not document the EIDRM error condition. |
fea681da | 346 | .SH NOTES |
f6652463 MK |
347 | The inclusion of |
348 | .I <sys/types.h> | |
349 | and | |
350 | .I <sys/ipc.h> | |
351 | isn't required on Linux or by any version of POSIX. | |
352 | However, | |
353 | some old implementations required the inclusion of these header files, | |
354 | and the SVID also documented their inclusion. | |
355 | Applications intended to be portable to such old systems may need | |
356 | to include these header files. | |
357 | .\" Like Linux, the FreeBSD man pages still document | |
358 | .\" the inclusion of these header files. | |
efeece04 | 359 | .PP |
f3021697 MK |
360 | The |
361 | .BR IPC_INFO , | |
0daa9e92 | 362 | .B MSG_STAT |
f3021697 MK |
363 | and |
364 | .B MSG_INFO | |
365 | operations are used by the | |
81a8f8e7 | 366 | .BR ipcs (1) |
f3021697 | 367 | program to provide information on allocated resources. |
282c1a35 MK |
368 | In the future these may modified or moved to a |
369 | .I /proc | |
370 | filesystem interface. | |
efeece04 | 371 | .PP |
e3e25559 MK |
372 | Various fields in the \fIstruct msqid_ds\fP were |
373 | typed as | |
374 | .I short | |
375 | under Linux 2.2 | |
376 | and have become | |
377 | .I long | |
378 | under Linux 2.4. | |
677f4766 | 379 | To take advantage of this, |
fea681da | 380 | a recompilation under glibc-2.1.91 or later should suffice. |
682edefb | 381 | (The kernel distinguishes old and new calls by an |
0daa9e92 | 382 | .B IPC_64 |
682edefb | 383 | flag in |
fea681da | 384 | .IR cmd .) |
47297adb | 385 | .SH SEE ALSO |
fea681da MK |
386 | .BR msgget (2), |
387 | .BR msgrcv (2), | |
388 | .BR msgsnd (2), | |
a9b305d6 | 389 | .BR capabilities (7), |
2c5e151c MK |
390 | .BR mq_overview (7), |
391 | .BR svipc (7) |