man2/msgctl.2

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