| 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) |