1.\" $OpenBSD: msgrcv.2,v 1.14 2007/09/03 14:37:52 millert 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: September 3 2007 $ 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.Fd #include <sys/types.h> 41.Fd #include <sys/ipc.h> 42.Fd #include <sys/msg.h> 43.Ft int 44.Fn msgrcv "int msqid" "void *msgp" "size_t msgsz" "long msgtyp" "int msgflg" 45.Sh DESCRIPTION 46The 47.Fn msgrcv 48function receives a message from the message queue specified in 49.Fa msqid , 50and places it into the structure pointed to by 51.Fa msgp . 52This structure should consist of the following members: 53.Bd -literal 54 long mtype; /* message type */ 55 char mtext[1]; /* body of message */ 56.Ed 57.Pp 58.Va mtype 59is an integer greater than 0 that can be used for selecting messages, 60.Va mtext 61is an array of bytes, with a size up to that of the system limit 62.Pq Dv MSGMAX . 63.Pp 64The value of 65.Fa msgtyp 66has one of the following meanings: 67.Bl -bullet 68.It 69.Fa msgtyp 70is greater than 0. 71The first message of type 72.Fa msgtyp 73will be received. 74.It 75.Fa msgtyp 76is equal to 0. 77The first message on the queue will be received. 78.It 79.Fa msgtyp 80is less than 0. 81The 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. 89If the received message 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 behavior of 100.Fn msgrcv 101depends on whether the 102.Dv IPC_NOWAIT 103flag is set in 104.Fa msgflg 105or not. 106If 107.Dv IPC_NOWAIT 108is set, 109.Fn msgrcv 110will immediately return a value of \-1, and set 111.Va errno 112to 113.Er EAGAIN . 114If 115.Dv IPC_NOWAIT 116is not set, the calling process will be blocked 117until: 118.Bl -bullet 119.It 120A message of the requested type becomes available on the message queue. 121.It 122The message queue is removed, in which case \-1 will be returned, and 123.Va errno 124set to 125.Er EINVAL . 126.It 127A signal is received and caught. 128\-1 is returned, and 129.Va errno 130set to 131.Er EINTR . 132.El 133.Pp 134If a message is successfully received, the data structure associated with 135.Fa msqid 136is updated as follows: 137.Bl -bullet 138.It 139.Va msg_cbytes 140is decremented by the size of the message. 141.It 142.Va msg_lrpid 143is set to the pid of the caller. 144.It 145.Va msg_lrtime 146is set to the current time. 147.It 148.Va msg_qnum 149is decremented by 1. 150.El 151.Sh RETURN VALUES 152Upon successful completion, 153.Fn msgrcv 154returns the number of bytes received into the 155.Va mtext 156field of the structure pointed to by 157.Fa msgp . 158Otherwise, \-1 is returned, and 159.Va errno 160set to indicate the error. 161.Sh ERRORS 162.Fn msgrcv 163will fail if: 164.Bl -tag -width Er 165.It Bq Er EINVAL 166.Fa msqid 167is not a valid message queue identifier. 168.Pp 169.Fa msgsz 170is less than 0. 171.It Bq Er E2BIG 172A matching message was received, but its size was greater than 173.Fa msgsz 174and the 175.Dv MSG_NOERROR 176flag was not set in 177.Fa msgflg . 178.It Bq Er EACCES 179The calling process does not have read access to the message queue. 180.It Bq Er EFAULT 181.Fa msgp 182points to an invalid address. 183.It Bq Er EINTR 184The system call was interrupted by the delivery of a signal. 185.It Bq Er ENOMSG 186There is no message of the requested type available on the message queue, 187and 188.Dv IPC_NOWAIT 189is set in 190.Fa msgflg . 191.It Bq Er EIDRM 192The message queue was removed while 193.Fn msgrcv 194was waiting for a message of the requested type to become available on it. 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 AT&T Unix System V. 202