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