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