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