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