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