Debian Codegraph @

upstream/debian-unstable/man2/msgctl.2

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