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 .\"
  30 .TH MSGCTL 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual"
  31 .SH NAME
  32 msgctl \- message control operations
  33 .SH SYNOPSIS
  34 .nf
  35 .B
  36 #include <sys/types.h>
  37 .B
  38 #include <sys/ipc.h>
  39 .B
  40 #include <sys/msg.h>
  41 .fi
  42 .sp
  43 .BI "int msgctl(int " msqid ,
  44 .BI "int " cmd ,
  45 .BI "struct msqid_ds *" buf );
  46 .SH DESCRIPTION
  47 This function performs the control operation specified by
  48 .I cmd
  49 on the message queue with identifier
  50 .IR msqid .
  51 Legal values for
  52 .I cmd
  53 are:
  54 .TP
  55 .B IPC_STAT
  56 Copy info from the message queue data structure associated with
  57 .I msqid
  58 into the structure pointed to by
  59 .IR buf .
  60 The caller must have read permission on the message queue.
  61 .TP
  62 .B IPC_SET
  63 Write the values of some members of the
  64 .B msqid_ds
  65 structure pointed to by
  66 .I buf
  67 to the message queue data structure, updating also its
  68 .B msg_ctime
  69 member.
  70 The following members of the structure can be updated:
  71 .nf
  72 .sp
  73 .ft B
  74         msg_perm.uid
  75         msg_perm.gid
  76         msg_perm.mode   \fR/* only lowest 9-bits */\fP
  77         msg_qbytes
  78 .fi
  79 .ft R
  80 .sp
  81 The calling process must have appropriate (probably, root) privileges
  82 or its effective user\-ID must be that of the creator
  83 .RI ( msg_perm.cuid )
  84 or owner
  85 .RI ( msg_perm.uid )
  86 of the message queue.
  87 Appropriate privilege (Linux: the
  88 .B CAP_IPC_RESOURCE
  89 capability) is required to raise the
  90 .B msg_qbytes
  91 value beyond the system parameter
  92 .BR MSGMNB .
  93 .TP
  94 .B IPC_RMID
  95 Immediately remove the message queue and its associated data structure,
  96 awakening all waiting reader and writer processes (with an error
  97 return and
  98 .B errno
  99 set to
 100 .BR EIDRM ).
 101 The calling process must have appropriate (probably, root) privileges
 102 or its effective user\-ID must be either that of the creator or owner
 103 of the message queue.
 104 .SH "RETURN VALUE"
 105 On success, the return value will be
 106 .BR 0 ,
 107 otherwise
 108 .B \-1
 109 with
 110 .B errno
 111 indicating the error.
 112 .SH ERRORS
 113 On failure,
 114 .B errno
 115 is set to one of the following:
 116 .TP 11
 117 .B EACCES
 118 The argument
 119 .I cmd
 120 is equal to
 121 .B IPC_STAT
 122 or
 123 .BR MSG_STAT ,
 124 but the calling process does not have read permission on the message queue
 125 .IR msqid ,
 126 and does not have the
 127 .B CAP_IPC_OWNER
 128 capability.
 129 .TP
 130 .B EFAULT
 131 The argument
 132 .I cmd
 133 has the value
 134 .B IPC_SET
 135 or
 136 .BR IPC_STAT ,
 137 but the address pointed to by
 138 .I buf
 139 isn't accessible.
 140 .TP
 141 .B EIDRM
 142 The message queue was removed.
 143 .TP
 144 .B EINVAL
 145 Invalid value for
 146 .I cmd
 147 or
 148 .IR msqid .
 149 .TP
 150 .B EPERM
 151 The argument
 152 .I cmd
 153 has the value
 154 .B IPC_SET
 155 or
 156 .BR IPC_RMID ,
 157 but the effective user ID of the calling process is not the creator
 158 (as found in
 159 .IR msg_perm.cuid )
 160 or the owner
 161 (as found in
 162 .IR msg_perm.uid )
 163 of the message queue,
 164 and the process is not privileged (Linux: it does not have the
 165 .B CAP_SYS_ADMIN
 166 capability).
 167 .SH NOTES
 168 Various fields in a \fIstruct msqid_ds\fP were shorts under Linux 2.2
 169 and have become longs under Linux 2.4. To take advantage of this,
 170 a recompilation under glibc-2.1.91 or later should suffice.
 171 (The kernel distinguishes old and new calls by a IPC_64 flag in
 172 .IR cmd .)
 173 .SH "CONFORMING TO"
 174 SVr4, SVID.  SVID does not document the EIDRM error condition.
 175 .SH "SEE ALSO"
 176 .BR msgget (2),
 177 .BR msgrcv (2),
 178 .BR msgsnd (2),
 179 .BR ipc (5),
 180 .BR capabilities (7)