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