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