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