man2/msgctl.2

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