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