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