1.\" $OpenBSD: msgrcv.2,v 1.18 2019/07/18 13:45:03 schwarze 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 $Mdocdate: July 18 2019 $ 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.In sys/msg.h 41.Ft int 42.Fn msgrcv "int msqid" "void *msgp" "size_t msgsz" "long msgtyp" "int msgflg" 43.Sh DESCRIPTION 44The 45.Fn msgrcv 46function receives a message from the message queue specified in 47.Fa msqid , 48and places it into the structure pointed to by 49.Fa msgp . 50This structure should consist of the following members: 51.Bd -literal 52 long mtype; /* message type */ 53 char mtext[1]; /* body of message */ 54.Ed 55.Pp 56.Fa mtype 57is an integer greater than 0 that can be used for selecting messages, 58.Fa mtext 59is an array of bytes, with a size up to that of the system limit 60.Pq Dv MSGMAX . 61.Pp 62The value of 63.Fa msgtyp 64has one of the following meanings: 65.Bl -bullet 66.It 67.Fa msgtyp 68is greater than 0. 69The first message of type 70.Fa msgtyp 71will be received. 72.It 73.Fa msgtyp 74is equal to 0. 75The first message on the queue will be received. 76.It 77.Fa msgtyp 78is less than 0. 79The first message of the lowest message type that is 80less than or equal to the absolute value of 81.Fa msgtyp 82will be received. 83.El 84.Pp 85.Fa msgsz 86specifies the maximum length of the requested message. 87If the received message has a length greater than 88.Fa msgsz 89it will be silently truncated if the 90.Dv MSG_NOERROR 91flag is set in 92.Fa msgflg , 93otherwise an error will be returned. 94.Pp 95If no matching message is present on the message queue specified by 96.Fa msqid , 97the behavior of 98.Fn msgrcv 99depends on whether the 100.Dv IPC_NOWAIT 101flag is set in 102.Fa msgflg 103or not. 104If 105.Dv IPC_NOWAIT 106is set, 107.Fn msgrcv 108will immediately return a value of \-1, and set 109.Va errno 110to 111.Er EAGAIN . 112If 113.Dv IPC_NOWAIT 114is not set, the calling process will be blocked 115until: 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 EIDRM . 124.It 125A signal is received and caught. 126\-1 is returned, and 127.Va errno 128set to 129.Er EINTR . 130.El 131.Pp 132If a message is successfully received, the data structure associated with 133.Fa msqid 134is updated as follows: 135.Bl -bullet 136.It 137.Fa msg_cbytes 138is decremented by the size of the message. 139.It 140.Fa msg_lrpid 141is set to the pid of the caller. 142.It 143.Fa msg_lrtime 144is set to the current time. 145.It 146.Fa msg_qnum 147is decremented by 1. 148.El 149.Sh RETURN VALUES 150Upon successful completion, 151.Fn msgrcv 152returns the number of bytes received into the 153.Fa mtext 154field of the structure pointed to by 155.Fa msgp . 156Otherwise, \-1 is returned, and 157.Va errno 158set to indicate the error. 159.Sh ERRORS 160.Fn msgrcv 161will fail if: 162.Bl -tag -width Er 163.It Bq Er EINVAL 164.Fa msqid 165is not a valid message queue identifier. 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 ENOMSG 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 was removed while 191.Fn msgrcv 192was waiting for a message of the requested type to become available on it. 193.El 194.Sh SEE ALSO 195.Xr msgctl 2 , 196.Xr msgget 2 , 197.Xr msgsnd 2 198.Sh STANDARDS 199The 200.Fn msgrcv 201function conforms to the X/Open System Interfaces option of 202.St -p1003.1-2008 . 203.Sh HISTORY 204Message queues first appeared in 205.At V.1 206and have been available since 207.Nx 1.0 . 208