lib/libc/sys/msgctl.2

   1 .\"     $NetBSD: msgctl.2,v 1.1 1995/10/16 23:49:15 jtc Exp $
   2 .\"
   3 .\" Copyright (c) 1995 Frank van der Linden
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"      This product includes software developed for the NetBSD Project
  17 .\"      by Frank van der Linden
  18 .\" 4. The name of the author may not be used to endorse or promote products
  19 .\"    derived from this software without specific prior written permission
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  22 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  23 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  24 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  25 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  26 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  30 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31 .\"
  32 .\" $FreeBSD$
  33 .\"/
  34 .Dd July 9, 2009
  35 .Dt MSGCTL 2
  36 .Os
  37 .Sh NAME
  38 .Nm msgctl
  39 .Nd message control operations
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In sys/types.h
  44 .In sys/ipc.h
  45 .In sys/msg.h
  46 .Ft int
  47 .Fn msgctl "int msqid" "int cmd" "struct msqid_ds *buf"
  48 .Sh DESCRIPTION
  49 The
  50 .Fn msgctl
  51 system call performs some control operations on the message queue specified
  52 by
  53 .Fa msqid .
  54 .Pp
  55 Each message queue has a data structure associated with it, parts of which
  56 may be altered by
  57 .Fn msgctl
  58 and parts of which determine the actions of
  59 .Fn msgctl .
  60 The data structure is defined in
  61 .In sys/msg.h
  62 and contains (amongst others) the following members:
  63 .Bd -literal
  64 struct msqid_ds {
  65         struct  ipc_perm msg_perm;      /* msg queue permission bits */
  66         struct  msg *msg_first; /* first message in the queue */
  67         struct  msg *msg_last;  /* last message in the queue */
  68         msglen_t msg_cbytes;    /* number of bytes in use on the queue */
  69         msgqnum_t msg_qnum;     /* number of msgs in the queue */
  70         msglen_t msg_qbytes;    /* max # of bytes on the queue */
  71         pid_t   msg_lspid;      /* pid of last msgsnd() */
  72         pid_t   msg_lrpid;      /* pid of last msgrcv() */
  73         time_t  msg_stime;      /* time of last msgsnd() */
  74         time_t  msg_rtime;      /* time of last msgrcv() */
  75         time_t  msg_ctime;      /* time of last msgctl() */
  76 };
  77 .Ed
  78 .Pp
  79 The
  80 .Vt ipc_perm
  81 structure used inside the
  82 .Vt msqid_ds
  83 structure is defined in
  84 .In sys/ipc.h
  85 and looks like this:
  86 .Bd -literal
  87 struct ipc_perm {
  88         uid_t           cuid;   /* creator user id */
  89         gid_t           cgid;   /* creator group id */
  90         uid_t           uid;    /* user id */
  91         gid_t           gid;    /* group id */
  92         mode_t          mode;   /* r/w permission */
  93         unsigned short  seq;    /* sequence # (to generate unique ipcid) */
  94         key_t           key;    /* user specified msg/sem/shm key */
  95 };
  96 .Ed
  97 .Pp
  98 The operation to be performed by
  99 .Fn msgctl
 100 is specified in
 101 .Fa cmd
 102 and is one of:
 103 .Bl -tag -width IPC_RMIDX
 104 .It Dv IPC_STAT
 105 Gather information about the message queue and place it in the
 106 structure pointed to by
 107 .Fa buf .
 108 .It Dv IPC_SET
 109 Set the value of the
 110 .Va msg_perm.uid ,
 111 .Va msg_perm.gid ,
 112 .Va msg_perm.mode
 113 and
 114 .Va msg_qbytes
 115 fields in the structure associated with
 116 .Fa msqid .
 117 The values are taken from the corresponding fields in the structure
 118 pointed to by
 119 .Fa buf .
 120 This operation can only be executed by the super-user, or a process that
 121 has an effective user id equal to either
 122 .Va msg_perm.cuid
 123 or
 124 .Va msg_perm.uid
 125 in the data structure associated with the message queue.
 126 The value of
 127 .Va msg_qbytes
 128 can only be increased by the super-user.
 129 Values for
 130 .Va msg_qbytes
 131 that exceed the system limit (MSGMNB from
 132 .In sys/msg.h )
 133 are silently truncated to that limit.
 134 .It Dv IPC_RMID
 135 Remove the message queue specified by
 136 .Fa msqid
 137 and destroy the data associated with it.
 138 Only the super-user or a process
 139 with an effective uid equal to the
 140 .Va msg_perm.cuid
 141 or
 142 .Va msg_perm.uid
 143 values in the data structure associated with the queue can do this.
 144 .El
 145 .Pp
 146 The permission to read from or write to a message queue (see
 147 .Xr msgsnd 2
 148 and
 149 .Xr msgrcv 2 )
 150 is determined by the
 151 .Va msg_perm.mode
 152 field in the same way as is
 153 done with files (see
 154 .Xr chmod 2 ) ,
 155 but the effective uid can match either the
 156 .Va msg_perm.cuid
 157 field or the
 158 .Va msg_perm.uid
 159 field, and the
 160 effective gid can match either
 161 .Va msg_perm.cgid
 162 or
 163 .Va msg_perm.gid .
 164 .Sh RETURN VALUES
 165 .Rv -std msgctl
 166 .Sh ERRORS
 167 The
 168 .Fn msgctl
 169 function
 170 will fail if:
 171 .Bl -tag -width Er
 172 .It Bq Er EPERM
 173 The
 174 .Fa cmd
 175 argument
 176 is equal to IPC_SET or IPC_RMID and the caller is not the super-user, nor does
 177 the effective uid match either the
 178 .Va msg_perm.uid
 179 or
 180 .Va msg_perm.cuid
 181 fields of the data structure associated with the message queue.
 182 .Pp
 183 An attempt is made to increase the value of
 184 .Va msg_qbytes
 185 through IPC_SET
 186 but the caller is not the super-user.
 187 .It Bq Er EACCES
 188 The command is IPC_STAT
 189 and the caller has no read permission for this message queue.
 190 .It Bq Er EINVAL
 191 The
 192 .Fa msqid
 193 argument
 194 is not a valid message queue identifier.
 195 .Pp
 196 .Va cmd
 197 is not a valid command.
 198 .It Bq Er EFAULT
 199 The
 200 .Fa buf
 201 argument
 202 specifies an invalid address.
 203 .El
 204 .Sh SEE ALSO
 205 .Xr msgget 2 ,
 206 .Xr msgrcv 2 ,
 207 .Xr msgsnd 2
 208 .Sh HISTORY
 209 Message queues appeared in the first release of
 210 .At V .