man2/msgctl.2

   1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
   2 .\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   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>
   8 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
   9 .\"     Added notes on CAP_IPC_OWNER requirement
  10 .\" Modified, 17 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  11 .\"     Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID
  12 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  13 .\"     Language and formatting clean-ups
  14 .\"     Added msqid_ds and ipc_perm structure definitions
  15 .\" 2005-08-02, mtk: Added IPC_INFO, MSG_INFO, MSG_STAT descriptions
  16 .\" 2018-03-20, dbueso: Added MSG_STAT_ANY description.
  17 .\"
  18 .TH MSGCTL 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  19 .SH NAME
  20 msgctl \- System V message control operations
  21 .SH LIBRARY
  22 Standard C library
  23 .RI ( libc ", " \-lc )
  24 .SH SYNOPSIS
  25 .nf
  26 .B #include <sys/msg.h>
  27 .PP
  28 .BI "int msgctl(int " msqid ", int " cmd ", struct msqid_ds *" buf );
  29 .fi
  30 .SH DESCRIPTION
  31 .BR msgctl ()
  32 performs the control operation specified by
  33 .I cmd
  34 on the System\ V message queue with identifier
  35 .IR msqid .
  36 .PP
  37 The
  38 .I msqid_ds
  39 data structure is defined in \fI<sys/msg.h>\fP as follows:
  40 .PP
  41 .in +4n
  42 .EX
  43 struct msqid_ds {
  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) */
  54 };
  55 .EE
  56 .in
  57 .PP
  58 The fields of the
  59 .I msqid_ds
  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
  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 ()
  81 .B IPC_SET
  82 operation.
  83 .TP
  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
  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.
 104 .PP
 105 The
 106 .I ipc_perm
 107 structure is defined as follows
 108 (the highlighted fields are settable using
 109 .BR IPC_SET ):
 110 .PP
 111 .in +4n
 112 .EX
 113 struct ipc_perm {
 114     key_t          __key;       /* Key supplied to msgget(2) */
 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 */
 120     unsigned short __seq;       /* Sequence number */
 121 };
 122 .EE
 123 .in
 124 .PP
 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
 143 Valid values for
 144 .I cmd
 145 are:
 146 .TP
 147 .B IPC_STAT
 148 Copy information from the kernel data structure associated with
 149 .I msqid
 150 into the
 151 .I msqid_ds
 152 structure pointed to by
 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
 158 .I msqid_ds
 159 structure pointed to by
 160 .I buf
 161 to the kernel data structure associated with this message queue,
 162 updating also its
 163 .I msg_ctime
 164 member.
 165 .IP
 166 The following members of the structure are updated:
 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 .
 172 .IP
 173 The effective UID of the calling process must match the owner
 174 .RI ( msg_perm.uid )
 175 or creator
 176 .RI ( msg_perm.cuid )
 177 of the message queue, or the caller must be privileged.
 178 Appropriate privilege (Linux: the
 179 .B CAP_SYS_RESOURCE
 180 capability) is required to raise the
 181 .I msg_qbytes
 182 value beyond the system parameter
 183 .BR MSGMNB .
 184 .TP
 185 .B IPC_RMID
 186 Immediately remove the message queue,
 187 awakening all waiting reader and writer processes (with an error
 188 return and
 189 .I errno
 190 set to
 191 .BR EIDRM ).
 192 The calling process must have appropriate privileges
 193 or its effective user ID must be either that of the creator or owner
 194 of the message queue.
 195 The third argument to
 196 .BR msgctl ()
 197 is ignored in this case.
 198 .TP
 199 .BR IPC_INFO " (Linux-specific)"
 200 Return information about system-wide message queue limits and
 201 parameters in the structure pointed to by
 202 .IR buf .
 203 This structure is of type
 204 .I msginfo
 205 (thus, a cast is required),
 206 defined in
 207 .I <sys/msg.h>
 208 if the
 209 .B _GNU_SOURCE
 210 feature test macro is defined:
 211 .IP
 212 .in +4n
 213 .EX
 214 struct msginfo {
 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
 221                     written in a single message */
 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 */
 231     unsigned short msgseg;
 232                  /* Maximum number of segments;
 233                     unused within kernel */
 234 };
 235 .EE
 236 .in
 237 .IP
 238 The
 239 .IR msgmni ,
 240 .IR msgmax ,
 241 and
 242 .I msgmnb
 243 settings can be changed via
 244 .I /proc
 245 files of the same name; see
 246 .BR proc (5)
 247 for details.
 248 .TP
 249 .BR MSG_INFO " (Linux-specific)"
 250 Return a
 251 .I msginfo
 252 structure containing the same information as for
 253 .BR IPC_INFO ,
 254 except that the following fields are returned with information
 255 about system resources consumed by message queues: the
 256 .I msgpool
 257 field returns the number of message queues that currently exist
 258 on the system; the
 259 .I msgmap
 260 field returns the total number of messages in all queues
 261 on the system; and the
 262 .I msgtql
 263 field returns the total number of bytes in all messages
 264 in all queues on the system.
 265 .TP
 266 .BR MSG_STAT " (Linux-specific)"
 267 Return a
 268 .I msqid_ds
 269 structure as for
 270 .BR IPC_STAT .
 271 However, the
 272 .I msqid
 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.
 276 .TP
 277 .BR MSG_STAT_ANY " (Linux-specific, since Linux 4.17)"
 278 Return a
 279 .I msqid_ds
 280 structure as for
 281 .BR MSG_STAT .
 282 However,
 283 .I msg_perm.mode
 284 is not checked for read access for
 285 .I msqid
 286 meaning that any user can employ this operation (just as any user may read
 287 .I /proc/sysvipc/msg
 288 to obtain the same information).
 289 .SH RETURN VALUE
 290 On success,
 291 .BR IPC_STAT ,
 292 .BR IPC_SET ,
 293 and
 294 .B IPC_RMID
 295 return 0.
 296 A successful
 297 .B IPC_INFO
 298 or
 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
 304 .B MSG_STAT
 305 or
 306 .B MSG_STAT_ANY
 307 operations to obtain information about all queues on the system.)
 308 A successful
 309 .B MSG_STAT
 310 or
 311 .B MSG_STAT_ANY
 312 operation returns the identifier of the queue whose index was given in
 313 .IR msqid .
 314 .PP
 315 On failure, \-1 is returned and
 316 .I errno
 317 is set to indicate the error.
 318 .SH ERRORS
 319 .TP
 320 .B EACCES
 321 The argument
 322 .I cmd
 323 is equal to
 324 .B IPC_STAT
 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
 331 capability in the user namespace that governs its IPC namespace.
 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 .
 352 Or: for a
 353 .B MSG_STAT
 354 operation, the index value specified in
 355 .I msqid
 356 referred to an array slot that is currently unused.
 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,
 372 and the caller is not privileged (Linux: does not have the
 373 .B CAP_SYS_ADMIN
 374 capability).
 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).
 386 .SH STANDARDS
 387 POSIX.1-2001, POSIX.1-2008, SVr4.
 388 .\" SVID does not document the EIDRM error condition.
 389 .SH NOTES
 390 The
 391 .BR IPC_INFO ,
 392 .BR MSG_STAT ,
 393 and
 394 .B MSG_INFO
 395 operations are used by the
 396 .BR ipcs (1)
 397 program to provide information on allocated resources.
 398 In the future these may modified or moved to a
 399 .I /proc
 400 filesystem interface.
 401 .PP
 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.
 409 To take advantage of this,
 410 a recompilation under glibc-2.1.91 or later should suffice.
 411 (The kernel distinguishes old and new calls by an
 412 .B IPC_64
 413 flag in
 414 .IR cmd .)
 415 .SH SEE ALSO
 416 .BR msgget (2),
 417 .BR msgrcv (2),
 418 .BR msgsnd (2),
 419 .BR capabilities (7),
 420 .BR mq_overview (7),
 421 .BR sysvipc (7)