original/man2/msgctl.2

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