Sweep-fix man page section order to match mdoc(7), part 1/5.
[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 $
9bb2a92d 32.\" $DragonFly: src/lib/libc/gen/msgrcv.3,v 1.3 2004/03/11 12:28:50 hmp Exp $
984263bc
MD
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
50The
51.Fn msgrcv
52function receives a message from the message queue specified in
53.Fa msqid ,
54and places it into the structure pointed to by
55.Fa msgp .
56This 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
63is an integer greater than 0 that can be used for selecting messages,
64.Va mtext
65is an array of bytes, with a size up to that of the system limit
66.Pf ( Dv MSGMAX ) .
67.Pp
68The value of
69.Fa msgtyp
70has one of the following meanings:
71.Bl -bullet
72.It
73The
74.Fa msgtyp
75argument
76is greater than 0. The first message of type
77.Fa msgtyp
78will be received.
79.It
80The
81.Fa msgtyp
82argument
83is equal to 0. The first message on the queue will be received.
84.It
85The
86.Fa msgtyp
87argument
88is less than 0. The first message of the lowest message type that is
89less than or equal to the absolute value of
90.Fa msgtyp
91will be received.
92.El
93.Pp
94The
95.Fa msgsz
96argument
97specifies the maximum length of the requested message.
98If the received
99message has a length greater than
100.Fa msgsz
101it will be silently truncated if the
102.Dv MSG_NOERROR
103flag is set in
104.Fa msgflg ,
105otherwise an error will be returned.
106.Pp
107If no matching message is present on the message queue specified by
108.Fa msqid ,
109the behavior of
110.Fn msgrcv
111depends on whether the
112.Dv IPC_NOWAIT
113flag is set in
114.Fa msgflg
115or not.
116If
117.Dv IPC_NOWAIT
118is set,
119.Fn msgrcv
120will immediately return a value of -1, and set
121.Va errno
122to
123.Er EAGAIN .
124If
125.Dv IPC_NOWAIT
126is not set, the calling process will be blocked
127until:
128.Bl -bullet
129.It
130A message of the requested type becomes available on the message queue.
131.It
132The message queue is removed, in which case -1 will be returned, and
133.Va errno
134set to
135.Er EINVAL .
136.It
137A signal is received and caught. -1 is returned, and
138.Va errno
139set to
140.Er EINTR .
141.El
142.Pp
143If a message is successfully received, the data structure associated with
144.Fa msqid
145is updated as follows:
146.Bl -bullet
147.It
148.Va msg_cbytes
149is decremented by the size of the message.
150.It
151.Va msg_lrpid
152is set to the pid of the caller.
153.It
154.Va msg_lrtime
155is set to the current time.
156.It
157.Va msg_qnum
158is decremented by 1.
159.El
160.Sh RETURN VALUES
161Upon successful completion,
162.Fn msgrcv
163returns the number of bytes received into the
164.Va mtext
165field of the structure pointed to by
166.Fa msgp .
167Otherwise, -1 is returned, and
168.Va errno
169set to indicate the error.
170.Sh ERRORS
171The
172.Fn msgrcv
173function
174will fail if:
175.Bl -tag -width Er
176.It Bq Er EINVAL
177The
178.Fa msqid
179argument
180is not a valid message queue identifier.
181.Pp
182The message queue was removed while
183.Fn msgrcv
184was waiting for a message of the requested type to become available on it.
185.Pp
186The
187.Fa msgsz
188argument
189is less than 0.
190.It Bq Er E2BIG
191A matching message was received, but its size was greater than
192.Fa msgsz
193and the
194.Dv MSG_NOERROR
195flag was not set in
196.Fa msgflg .
197.It Bq Er EACCES
198The calling process does not have read access to the message queue.
199.It Bq Er EFAULT
200The
201.Fa msgp
202argument
203points to an invalid address.
204.It Bq Er EINTR
205The system call was interrupted by the delivery of a signal.
206.It Bq Er EAGAIN
207There is no message of the requested type available on the message queue,
208and
209.Dv IPC_NOWAIT
210is 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 BUGS
9bb2a92d
HP
218.Tn Nx Ns ,
219.Dx Ns ,
984263bc
MD
220and
221.Fx
222do not define the
223.Er EIDRM
224error value, which should be used in
225the case of a removed message queue, nor the
226.Er ENOMSG
227value, which
228should be used when no suitable message is available and
229.Dv IPC_NOWAIT
230is set.
231.Sh HISTORY
232Message queues appeared in the first release of
233.At V .