lib/libc/gen/msgctl.3

   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: src/lib/libc/gen/msgctl.3,v 1.8.2.7 2003/03/13 18:05:37 trhodes Exp $
  33 .\" $DragonFly: src/lib/libc/gen/msgctl.3,v 1.3 2006/05/26 19:39:36 swildner Exp $
  34 .\"/
  35 .Dd November 24, 1997
  36 .Dt MSGCTL 3
  37 .Os
  38 .Sh NAME
  39 .Nm msgctl
  40 .Nd message control operations
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In sys/types.h
  45 .In sys/ipc.h
  46 .In sys/msg.h
  47 .Ft int
  48 .Fn msgctl "int msqid" "int cmd" "struct msqid_ds *buf"
  49 .Sh DESCRIPTION
  50 The
  51 .Fn msgctl
  52 system call performs some control operations on the message queue specified
  53 by
  54 .Fa msqid .
  55 .Pp
  56 Each message queue has a data structure associated with it, parts of which
  57 may be altered by
  58 .Fn msgctl
  59 and parts of which determine the actions of
  60 .Fn msgctl .
  61 The data structure is defined in
  62 .In sys/msg.h
  63 and contains (amongst others) the following members:
  64 .Bd -literal
  65 struct msqid_ds {
  66         struct  ipc_perm msg_perm;      /* msg queue permission bits */
  67         struct  msg *msg_first; /* first message in the queue */
  68         struct  msg *msg_last;  /* last message in the queue */
  69         u_long  msg_cbytes;     /* number of bytes in use on the queue */
  70         u_long  msg_qnum;       /* number of msgs in the queue */
  71         u_long  msg_qbytes;     /* max # of bytes on the queue */
  72         pid_t   msg_lspid;      /* pid of last msgsnd() */
  73         pid_t   msg_lrpid;      /* pid of last msgrcv() */
  74         time_t  msg_stime;      /* time of last msgsnd() */
  75         long    msg_pad1;
  76         time_t  msg_rtime;      /* time of last msgrcv() */
  77         long    msg_pad2;
  78         time_t  msg_ctime;      /* time of last msgctl() */
  79         long    msg_pad3;
  80         long    msg_pad4[4];
  81 };
  82 .Ed
  83 .Pp
  84 The
  85 .Vt ipc_perm
  86 structure used inside the
  87 .Vt shmid_ds
  88 structure is defined in
  89 .In sys/ipc.h
  90 and looks like this:
  91 .Bd -literal
  92 struct ipc_perm {
  93         ushort  cuid;   /* creator user id */
  94         ushort  cgid;   /* creator group id */
  95         ushort  uid;    /* user id */
  96         ushort  gid;    /* group id */
  97         ushort  mode;   /* r/w permission */
  98         ushort  seq;    /* sequence # (to generate unique msg/sem/shm id) */
  99         key_t   key;    /* user specified msg/sem/shm key */
 100 };
 101 .Ed
 102 .Pp
 103 The operation to be performed by
 104 .Fn msgctl
 105 is specified in
 106 .Fa cmd
 107 and is one of:
 108 .Bl -tag -width IPC_RMIDX
 109 .It Dv IPC_STAT
 110 Gather information about the message queue and place it in the
 111 structure pointed to by
 112 .Fa buf .
 113 .It Dv IPC_SET
 114 Set the value of the
 115 .Va msg_perm.uid ,
 116 .Va msg_perm.gid ,
 117 .Va msg_perm.mode
 118 and
 119 .Va msg_qbytes
 120 fields in the structure associated with
 121 .Fa msqid .
 122 The values are taken from the corresponding fields in the structure
 123 pointed to by
 124 .Fa buf .
 125 This operation can only be executed by the super-user, or a process that
 126 has an effective user id equal to either
 127 .Va msg_perm.cuid
 128 or
 129 .Va msg_perm.uid
 130 in the data structure associated with the message queue.
 131 The value of
 132 .Va msg_qbytes
 133 can only be increased by the super-user.
 134 Values for
 135 .Va msg_qbytes
 136 that exceed the system limit (MSGMNB from
 137 .In sys/msg.h )
 138 are silently truncated to that limit.
 139 .It Dv IPC_RMID
 140 Remove the message queue specified by
 141 .Fa msqid
 142 and destroy the data associated with it.
 143 Only the super-user or a process
 144 with an effective uid equal to the
 145 .Va msg_perm.cuid
 146 or
 147 .Va msg_perm.uid
 148 values in the data structure associated with the queue can do this.
 149 .El
 150 .Pp
 151 The permission to read from or write to a message queue (see
 152 .Xr msgsnd 3
 153 and
 154 .Xr msgrcv 3 )
 155 is determined by the
 156 .Va msg_perm.mode
 157 field in the same way as is
 158 done with files (see
 159 .Xr chmod 2 ) ,
 160 but the effective uid can match either the
 161 .Va msg_perm.cuid
 162 field or the
 163 .Va msg_perm.uid
 164 field, and the
 165 effective gid can match either
 166 .Va msg_perm.cgid
 167 or
 168 .Va msg_perm.gid .
 169 .Sh RETURN VALUES
 170 .Rv -std msgctl
 171 .Sh ERRORS
 172 The
 173 .Fn msgctl
 174 function
 175 will fail if:
 176 .Bl -tag -width Er
 177 .It Bq Er EPERM
 178 The
 179 .Fa cmd
 180 argument
 181 is equal to IPC_SET or IPC_RMID and the caller is not the super-user, nor does
 182 the effective uid match either the
 183 .Va msg_perm.uid
 184 or
 185 .Va msg_perm.cuid
 186 fields of the data structure associated with the message queue.
 187 .Pp
 188 An attempt is made to increase the value of
 189 .Va msg_qbytes
 190 through IPC_SET
 191 but the caller is not the super-user.
 192 .It Bq Er EACCES
 193 The command is IPC_STAT
 194 and the caller has no read permission for this message queue.
 195 .It Bq Er EINVAL
 196 The
 197 .Fa msqid
 198 argument
 199 is not a valid message queue identifier.
 200 .Pp
 201 .Va cmd
 202 is not a valid command.
 203 .It Bq Er EFAULT
 204 The
 205 .Fa buf
 206 argument
 207 specifies an invalid address.
 208 .El
 209 .Sh SEE ALSO
 210 .Xr msgget 3 ,
 211 .Xr msgrcv 3 ,
 212 .Xr msgsnd 3
 213 .Sh HISTORY
 214 Message queues appeared in the first release of
 215 .At V .