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