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