1.\" $NetBSD: msgrcv.2,v 1.1 1995/10/16 23:49:20 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/msgrcv.3,v 1.8.2.7 2003/03/15 15:11:05 trhodes Exp $ 33.\" 34.Dd January 4, 2014 35.Dt MSGRCV 2 36.Os 37.Sh NAME 38.Nm msgrcv 39.Nd receive a message from a message queue 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 msgrcv "int msqid" "void *msgp" "size_t msgsz" "long msgtyp" "int msgflg" 48.Sh DESCRIPTION 49The 50.Fn msgrcv 51system call receives a message from the message queue specified in 52.Fa msqid , 53and places it into the structure pointed to by 54.Fa msgp . 55This structure should consist of the following members: 56.Bd -literal 57 long mtype; /* message type */ 58 char mtext[1]; /* body of message */ 59.Ed 60.Pp 61.Va mtype 62is an integer greater than 0 that can be used for selecting messages, 63.Va mtext 64is an array of bytes, with a size up to that of the system limit 65.Pf ( Dv MSGMAX ) . 66.Pp 67The value of 68.Fa msgtyp 69has one of the following meanings: 70.Bl -bullet 71.It 72The 73.Fa msgtyp 74argument 75is greater than 0. 76The first message of type 77.Fa msgtyp 78will be received. 79.It 80The 81.Fa msgtyp 82argument 83is equal to 0. 84The first message on the queue will be received. 85.It 86The 87.Fa msgtyp 88argument 89is less than 0. 90The first message of the lowest message type that is 91less than or equal to the absolute value of 92.Fa msgtyp 93will be received. 94.El 95.Pp 96The 97.Fa msgsz 98argument 99specifies the maximum length of the requested message. 100If the received 101message has a length greater than 102.Fa msgsz 103it will be silently truncated if the 104.Dv MSG_NOERROR 105flag is set in 106.Fa msgflg , 107otherwise an error will be returned. 108.Pp 109If no matching message is present on the message queue specified by 110.Fa msqid , 111the behavior of 112.Fn msgrcv 113depends on whether the 114.Dv IPC_NOWAIT 115flag is set in 116.Fa msgflg 117or not. 118If 119.Dv IPC_NOWAIT 120is set, 121.Fn msgrcv 122will immediately return a value of -1, and set 123.Va errno 124to 125.Er EAGAIN . 126If 127.Dv IPC_NOWAIT 128is not set, the calling process will be blocked 129until: 130.Bl -bullet 131.It 132A message of the requested type becomes available on the message queue. 133.It 134The message queue is removed, in which case -1 will be returned, and 135.Va errno 136set to 137.Er EINVAL . 138.It 139A signal is received and caught. 140-1 is returned, and 141.Va errno 142set to 143.Er EINTR . 144.El 145.Pp 146If a message is successfully received, the data structure associated with 147.Fa msqid 148is updated as follows: 149.Bl -bullet 150.It 151.Va msg_cbytes 152is decremented by the size of the message. 153.It 154.Va msg_lrpid 155is set to the pid of the caller. 156.It 157.Va msg_lrtime 158is set to the current time. 159.It 160.Va msg_qnum 161is decremented by 1. 162.El 163.Sh RETURN VALUES 164Upon successful completion, 165.Fn msgrcv 166returns the number of bytes received into the 167.Va mtext 168field of the structure pointed to by 169.Fa msgp . 170Otherwise, -1 is returned, and 171.Va errno 172set to indicate the error. 173.Sh ENVIRONMENT 174The XSI Interprocess Communication family of functions is also available 175as an implementation in userspace. 176To use it, the 177.Xr sysvipcd 8 178daemon has to be running. 179.Pp 180If the 181.Ev USR_SYSVIPC 182variable is set in a process' environment, the process and its children 183will use the userspace implementation. 184.Sh ERRORS 185The 186.Fn msgrcv 187system call will fail if: 188.Bl -tag -width Er 189.It Bq Er EINVAL 190The 191.Fa msqid 192argument 193is not a valid message queue identifier. 194.Pp 195The message queue was removed while 196.Fn msgrcv 197was waiting for a message of the requested type to become available on it. 198.Pp 199The 200.Fa msgsz 201argument 202is less than 0. 203.It Bq Er E2BIG 204A matching message was received, but its size was greater than 205.Fa msgsz 206and the 207.Dv MSG_NOERROR 208flag was not set in 209.Fa msgflg . 210.It Bq Er EACCES 211The calling process does not have read access to the message queue. 212.It Bq Er EFAULT 213The 214.Fa msgp 215argument 216points to an invalid address. 217.It Bq Er EINTR 218The system call was interrupted by the delivery of a signal. 219.It Bq Er EAGAIN 220There is no message of the requested type available on the message queue, 221and 222.Dv IPC_NOWAIT 223is set in 224.Fa msgflg . 225.El 226.Sh SEE ALSO 227.Xr msgctl 2 , 228.Xr msgget 2 , 229.Xr msgsnd 2 230.Sh HISTORY 231Message queues appeared in the first release of 232.At V . 233.Sh AUTHORS 234.An -nosplit 235The 236.Dx 237specific userspace implementation (see 238.Sx ENVIRONMENT ) 239was written by 240.An Larisa Grigore . 241.Sh BUGS 242.Nx , 243.Dx , 244and 245.Fx 246do not define the 247.Er EIDRM 248error value, which should be used in 249the case of a removed message queue, nor the 250.Er ENOMSG 251value, which 252should be used when no suitable message is available and 253.Dv IPC_NOWAIT 254is set. 255