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