1.\" $OpenBSD: msgrcv.2,v 1.10 2001/08/06 10:42:26 mpech Exp $ 2.\" $NetBSD: msgrcv.2,v 1.2 1997/03/27 08:20:37 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 August 17, 1995 34.Dt MSGRCV 2 35.Os 36.Sh NAME 37.Nm msgrcv 38.Nd receive a message from a message queue 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 msgrcv "int msqid" "void *msgp" "size_t msgsz" "long msgtyp" "int msgflg" 45.Sh DESCRIPTION 46The 47.Fn msgrcv 48function receives a message from the message queue specified in 49.Fa msqid , 50and places it into the structure pointed to by 51.Fa msgp . 52This structure should consist of the following members: 53.Bd -literal 54 long mtype; /* message type */ 55 char mtext[1]; /* body of message */ 56.Ed 57.Pp 58.Va mtype 59is an integer greater than 0 that can be used for selecting messages, 60.Va mtext 61is an array of bytes, with a size up to that of the system limit 62.Pq Dv MSGMAX . 63.Pp 64The value of 65.Fa msgtyp 66has one of the following meanings: 67.Bl -bullet 68.It 69.Fa msgtyp 70is greater than 0. 71The first message of type 72.Fa msgtyp 73will be received. 74.It 75.Fa msgtyp 76is equal to 0. 77The first message on the queue will be received. 78.It 79.Fa msgtyp 80is less than 0. 81The first message of the lowest message type that is 82less than or equal to the absolute value of 83.Fa msgtyp 84will be received. 85.El 86.Pp 87.Fa msgsz 88specifies the maximum length of the requested message. 89If the received message has a length greater than 90.Fa msgsz 91it will be silently truncated if the 92.Dv MSG_NOERROR 93flag is set in 94.Fa msgflg , 95otherwise an error will be returned. 96.Pp 97If no matching message is present on the message queue specified by 98.Fa msqid , 99the behavior of 100.Fn msgrcv 101depends on whether the 102.Dv IPC_NOWAIT 103flag is set in 104.Fa msgflg 105or not. 106If 107.Dv IPC_NOWAIT 108is set, 109.Fn msgrcv 110will immediately return a value of \-1, and set 111.Va errno 112to 113.Er EAGAIN . 114If 115.Dv IPC_NOWAIT 116is not set, the calling process will be blocked 117until: 118.Bl -bullet 119.It 120A message of the requested type becomes available on the message queue. 121.It 122The message queue is removed, in which case \-1 will be returned, and 123.Va errno 124set to 125.Er EINVAL . 126.It 127A signal is received and caught. 128\-1 is returned, and 129.Va errno 130set to 131.Er EINTR . 132.El 133.Pp 134If a message is successfully received, the data structure associated with 135.Fa msqid 136is updated as follows: 137.Bl -bullet 138.It 139.Va msg_cbytes 140is decremented by the size of the message. 141.It 142.Va msg_lrpid 143is set to the pid of the caller. 144.It 145.Va msg_lrtime 146is set to the current time. 147.It 148.Va msg_qnum 149is decremented by 1. 150.El 151.Sh RETURN VALUES 152Upon successful completion, 153.Fn msgrcv 154returns the number of bytes received into the 155.Va mtext 156field of the structure pointed to by 157.Fa msgp . 158Otherwise, \-1 is returned, and 159.Va errno 160set to indicate the error. 161.Sh ERRORS 162.Fn msgrcv 163will fail if: 164.Bl -tag -width Er 165.It Bq Er EINVAL 166.Fa msqid 167is not a valid message queue identifier 168.Pp 169The message queue was removed while 170.Fn msgrcv 171was waiting for a message of the requested type to become available on it. 172.Pp 173.Fa msgsz 174is less than 0. 175.It Bq Er E2BIG 176A matching message was received, but its size was greater than 177.Fa msgsz 178and the 179.Dv MSG_NOERROR 180flag was not set in 181.Fa msgflg . 182.It Bq Er EACCES 183The calling process does not have read access to the message queue. 184.It Bq Er EFAULT 185.Fa msgp 186points to an invalid address. 187.It Bq Er EINTR 188The system call was interrupted by the delivery of a signal. 189.It Bq Er EAGAIN 190There is no message of the requested type available on the message queue, 191and 192.Dv IPC_NOWAIT 193is set in 194.Fa msgflg . 195.El 196.Sh SEE ALSO 197.Xr msgctl 2 , 198.Xr msgget 2 , 199.Xr msgsnd 2 200.Sh BUGS 201.Ox 202does not define the 203.Er EIDRM 204error value, which should be used in 205the case of a removed message queue, nor the 206.Er ENOMSG 207value, which 208should be used when no suitable message is available and 209.Dv IPC_NOWAIT 210is set. 211.Sh HISTORY 212Message queues appeared in the first release of AT&T Unix System V. 213