1.\" $NetBSD: msgrcv.2,v 1.13 2002/02/08 01:28:19 ross 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. The remaining 54fields will contain the contents of the message. The following is 55an example of what this user-defined structure might look like: 56.Bd -literal 57struct mymsg { 58 long mtype; /* message type */ 59 char mtext[1]; /* body of message */ 60}; 61.Ed 62.Pp 63.Va mtype 64is an integer greater than 0 that can be used to select messages. 65.Va mtext 66is an array of bytes, with size up to the system limit 67.Dv MSGMAX . 68.Pp 69The value of 70.Fa msgtyp 71has one of the following meanings: 72.Bl -bullet 73.It 74.Fa msgtyp 75is greater than 0. The first message of type 76.Fa msgtyp 77will be received. 78.It 79.Fa msgtyp 80is equal to 0. The first message on the queue will be received. 81.It 82.Fa msgtyp 83is less than 0. The first message of the lowest message type that is 84less than or equal to the absolute value of 85.Fa msgtyp 86will be received. 87.El 88.Pp 89.Fa msgsz 90specifies the maximum length of the requested message. If the received 91message has a length greater than 92.Fa msgsz 93it will be silently truncated if the 94.Dv MSG_NOERROR 95flag is set in 96.Fa msgflg , 97otherwise an error will be returned. 98.Pp 99If no matching message is present on the message queue specified by 100.Fa msqid , 101the behaviour of 102.Fn msgrcv 103depends on whether the 104.Dv IPC_NOWAIT 105flag is set in 106.Fa msgflg 107or not. If 108.Dv IPC_NOWAIT 109is set, then 110.Fn msgrcv 111will immediately return a value of -1 and set 112.Va errno 113to 114.Er EAGAIN . 115If 116.Dv IPC_NOWAIT 117is not set, the calling process will block until: 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 EIDRM . 126.It 127A signal is received and caught. -1 is returned and 128.Va errno 129is set to 130.Er EINTR . 131.El 132.Pp 133If a message is successfully received, the data structure associated with 134.Fa msqid 135is updated as follows: 136.Bl -bullet 137.It 138.Va msg_lrpid 139is set to the pid of the caller. 140.It 141.Va msg_lrtime 142is set to the current time. 143.It 144.Va msg_qnum 145is decremented by 1. 146.El 147.Sh RETURN VALUES 148Upon successful completion, 149.Fn msgrcv 150returns the number of bytes received into the 151.Va mtext 152field of the structure pointed to by 153.Fa msgp . 154Otherwise, -1 is returned, and 155.Va errno 156set to indicate the error. 157.Sh ERRORS 158.Fn msgrcv 159will fail if: 160.Bl -tag -width Er 161.It Bq Er EINVAL 162.Fa msqid 163is not a valid message queue identifier 164.Pp 165The message queue was removed while 166.Fn msgrcv 167was waiting for a message of the requested type to become available in it. 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 EAGAIN 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 identifier 193.Fa msqid 194is removed from the system. 195.It Bq Er ENOMSG 196The queue does not contain a message of the desired type and 197.Dv IPC_NOWAIT 198is set. 199.El 200.Sh SEE ALSO 201.Xr msgctl 2 , 202.Xr msgget 2 , 203.Xr msgsnd 2 204.Sh STANDARDS 205The 206.Nm 207system call conforms to 208.St -xsh5 . 209.Sh HISTORY 210Message queues appeared in the first release of 211.At V . 212