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