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.\" $FreeBSD: src/lib/libc/gen/msgctl.3,v 1.8.2.7 2003/03/13 18:05:37 trhodes Exp $ 33.\" 34.Dd January 4, 2014 35.Dt MSGCTL 2 36.Os 37.Sh NAME 38.Nm msgctl 39.Nd message control operations 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In sys/types.h 44.In sys/ipc.h 45.In sys/msg.h 46.Ft int 47.Fn msgctl "int msqid" "int cmd" "struct msqid_ds *buf" 48.Sh DESCRIPTION 49The 50.Fn msgctl 51system call performs some control operations on the message queue specified 52by 53.Fa msqid . 54.Pp 55Each message queue has a data structure associated with it, parts of which 56may be altered by 57.Fn msgctl 58and parts of which determine the actions of 59.Fn msgctl . 60The data structure is defined in 61.In sys/msg.h 62and contains (amongst others) the following members: 63.Bd -literal 64struct msqid_ds { 65 struct ipc_perm msg_perm; /* msg queue permission bits */ 66 struct msg *msg_first; /* first message in the queue */ 67 struct msg *msg_last; /* last message in the queue */ 68 u_long msg_cbytes; /* number of bytes in use on the queue */ 69 u_long msg_qnum; /* number of msgs in the queue */ 70 u_long msg_qbytes; /* max # of bytes on the queue */ 71 pid_t msg_lspid; /* pid of last msgsnd() */ 72 pid_t msg_lrpid; /* pid of last msgrcv() */ 73 time_t msg_stime; /* time of last msgsnd() */ 74 long msg_pad1; 75 time_t msg_rtime; /* time of last msgrcv() */ 76 long msg_pad2; 77 time_t msg_ctime; /* time of last msgctl() */ 78 long msg_pad3; 79 long msg_pad4[4]; 80}; 81.Ed 82.Pp 83The 84.Vt ipc_perm 85structure used inside the 86.Vt shmid_ds 87structure is defined in 88.In sys/ipc.h 89and looks like this: 90.Bd -literal 91struct ipc_perm { 92 ushort cuid; /* creator user id */ 93 ushort cgid; /* creator group id */ 94 ushort uid; /* user id */ 95 ushort gid; /* group id */ 96 ushort mode; /* r/w permission */ 97 ushort seq; /* sequence # (to generate unique msg/sem/shm id) */ 98 key_t key; /* user specified msg/sem/shm key */ 99}; 100.Ed 101.Pp 102The operation to be performed by 103.Fn msgctl 104is specified in 105.Fa cmd 106and is one of: 107.Bl -tag -width ".Dv IPC_RMIDX" 108.It Dv IPC_STAT 109Gather information about the message queue and place it in the 110structure pointed to by 111.Fa buf . 112.It Dv IPC_SET 113Set the value of the 114.Va msg_perm.uid , 115.Va msg_perm.gid , 116.Va msg_perm.mode 117and 118.Va msg_qbytes 119fields in the structure associated with 120.Fa msqid . 121The values are taken from the corresponding fields in the structure 122pointed to by 123.Fa buf . 124This operation can only be executed by the super-user, or a process that 125has an effective user id equal to either 126.Va msg_perm.cuid 127or 128.Va msg_perm.uid 129in the data structure associated with the message queue. 130The value of 131.Va msg_qbytes 132can only be increased by the super-user. 133Values for 134.Va msg_qbytes 135that exceed the system limit (MSGMNB from 136.In sys/msg.h ) 137are silently truncated to that limit. 138.It Dv IPC_RMID 139Remove the message queue specified by 140.Fa msqid 141and destroy the data associated with it. 142Only the super-user or a process 143with an effective uid equal to the 144.Va msg_perm.cuid 145or 146.Va msg_perm.uid 147values in the data structure associated with the queue can do this. 148.El 149.Pp 150The permission to read from or write to a message queue (see 151.Xr msgsnd 2 152and 153.Xr msgrcv 2 ) 154is determined by the 155.Va msg_perm.mode 156field in the same way as is 157done with files (see 158.Xr chmod 2 ) , 159but the effective uid can match either the 160.Va msg_perm.cuid 161field or the 162.Va msg_perm.uid 163field, and the 164effective gid can match either 165.Va msg_perm.cgid 166or 167.Va msg_perm.gid . 168.Sh RETURN VALUES 169.Rv -std msgctl 170.Sh ENVIRONMENT 171The XSI Interprocess Communication family of functions is also available 172as an implementation in userspace. 173To use it, the 174.Xr sysvipcd 8 175daemon has to be running. 176.Pp 177If the 178.Ev USR_SYSVIPC 179variable is set in a process' environment, the process and its children 180will use the userspace implementation. 181.Sh ERRORS 182The 183.Fn msgctl 184system call will fail if: 185.Bl -tag -width Er 186.It Bq Er EPERM 187The 188.Fa cmd 189argument 190is equal to 191.Dv IPC_SET 192or 193.Dv IPC_RMID 194and the caller is not the super-user, nor does 195the effective uid match either the 196.Va msg_perm.uid 197or 198.Va msg_perm.cuid 199fields of the data structure associated with the message queue. 200.Pp 201An attempt is made to increase the value of 202.Va msg_qbytes 203through 204.Dv IPC_SET 205but the caller is not the super-user. 206.It Bq Er EACCES 207The command is 208.Dv IPC_STAT 209and the caller has no read permission for this message queue. 210.It Bq Er EINVAL 211The 212.Fa msqid 213argument 214is not a valid message queue identifier. 215.Pp 216.Va cmd 217is not a valid command. 218.It Bq Er EFAULT 219The 220.Fa buf 221argument 222specifies an invalid address. 223.El 224.Sh SEE ALSO 225.Xr msgget 2 , 226.Xr msgrcv 2 , 227.Xr msgsnd 2 228.Sh HISTORY 229Message queues appeared in the first release of 230.At V . 231.Sh AUTHORS 232.An -nosplit 233The 234.Dx 235specific userspace implementation (see 236.Sx ENVIRONMENT ) 237was written by 238.An Larisa Grigore . 239