jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: recv.2,v 1.52 2025/08/11 05:36:18 guenther Exp $
2.\" $NetBSD: recv.2,v 1.6 1995/02/27 12:36:08 cgd Exp $
3.\"
4.\" Copyright (c) 1983, 1990, 1991, 1993
5.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors
16.\" may be used to endorse or promote products derived from this software
17.\" without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\" @(#)recv.2 8.3 (Berkeley) 2/21/94
32.\"
33.Dd $Mdocdate: August 11 2025 $
34.Dt RECV 2
35.Os
36.Sh NAME
37.Nm recv ,
38.Nm recvfrom ,
39.Nm recvmsg ,
40.Nm recvmmsg
41.Nd receive a message from a socket
42.Sh SYNOPSIS
43.In sys/socket.h
44.Ft ssize_t
45.Fn recv "int s" "void *buf" "size_t len" "int flags"
46.Ft ssize_t
47.Fn recvfrom "int s" "void *buf" "size_t len" "int flags" "struct sockaddr *from" "socklen_t *fromlen"
48.Ft ssize_t
49.Fn recvmsg "int s" "struct msghdr *msg" "int flags"
50.Ft int
51.Fn recvmmsg "int s" "struct mmsghdr *mmsg" "unsigned int vlen" "int flags" "struct timespec *timeout"
52.Sh DESCRIPTION
53.Fn recv ,
54.Fn recvfrom ,
55.Fn recvmsg ,
56and
57.Fn recvmmsg
58are used to receive messages from a socket,
59.Fa s .
60.Fn recv
61is normally used only on a
62.Em connected
63socket (see
64.Xr connect 2 ) .
65.Fn recvfrom ,
66.Fn recvmsg ,
67and
68.Fn recvmmsg
69may be used to receive
70data on a socket whether or not it is connection-oriented.
71.Pp
72.Fn recv
73is identical to
74.Fn recvfrom
75with a null
76.Fa from
77parameter.
78.Pp
79If
80.Fa from
81is non-null and the socket is not connection-oriented,
82the source address of the message is filled in.
83.Fa fromlen
84is a value-result parameter, initialized to the size of
85the buffer associated with
86.Fa from ,
87and modified on return to indicate the actual size of the
88address stored there.
89.Pp
90If no messages are available at the socket, the
91receive call waits for a message to arrive, unless
92the socket is nonblocking (see
93.Xr fcntl 2 )
94in which case the value
95\-1 is returned and the external variable
96.Va errno
97set to
98.Er EAGAIN .
99The receive calls normally return any data available,
100up to the requested amount,
101rather than waiting for receipt of the full amount requested;
102this behavior is affected by the socket-level options
103.Dv SO_RCVLOWAT
104and
105.Dv SO_RCVTIMEO
106described in
107.Xr getsockopt 2 .
108.Pp
109The
110.Xr select 2
111or
112.Xr poll 2
113system calls may be used to determine when more data arrive.
114.Pp
115The
116.Fa flags
117argument is the bitwise OR of zero or more of the following values:
118.Pp
119.Bl -tag -width "MSG_CMSG_CLOEXECXX" -offset indent -compact
120.It Dv MSG_OOB
121process out-of-band data
122.It Dv MSG_PEEK
123peek at incoming message
124.It Dv MSG_WAITALL
125wait for full request or error
126.It Dv MSG_DONTWAIT
127don't block
128.It Dv MSG_CMSG_CLOEXEC
129set the close-on-exec flag on received file descriptors
130.It Dv MSG_CMSG_CLOFORK
131set the close-on-fork flag on received file descriptors
132.El
133.Pp
134The
135.Dv MSG_OOB
136flag requests receipt of out-of-band data
137that would not be received in the normal data stream.
138Some protocols place expedited data at the head of the normal
139data queue, and thus this flag cannot be used with such protocols.
140The
141.Dv MSG_PEEK
142flag causes the receive operation to return data
143from the beginning of the receive queue without removing that
144data from the queue.
145Thus, a subsequent receive call will return the same data.
146The
147.Dv MSG_WAITALL
148flag requests that the operation block until
149the full request is satisfied.
150However, the call may still return less data than requested
151if a signal is caught, an error or disconnect occurs,
152or the next data to be received is of a different type than that returned.
153The
154.Dv MSG_DONTWAIT
155flag requests the call to return when it would block otherwise.
156If no data is available,
157.Va errno
158is set to
159.Er EAGAIN .
160This flag is not available in strict ANSI or C99 compilation mode.
161The
162.Dv MSG_CMSG_CLOEXEC
163and
164.Dv MSG_CMSG_CLOFORK
165flags request that any file descriptors received as ancillary data with
166.Fn recvmsg
167and
168.Fn recvmmsg
169(see below)
170have their close-on-exec flag or close-on-fork flag, respectively, set.
171.Pp
172The
173.Fn recvmsg
174call uses a
175.Fa msghdr
176structure to minimize the number of directly supplied parameters.
177This structure has the following form, as defined in
178.In sys/socket.h :
179.Bd -literal
180struct msghdr {
181 void *msg_name; /* optional address */
182 socklen_t msg_namelen; /* size of address */
183 struct iovec *msg_iov; /* scatter/gather array */
184 unsigned int msg_iovlen; /* # elements in msg_iov */
185 void *msg_control; /* ancillary data, see below */
186 socklen_t msg_controllen; /* ancillary data buffer len */
187 int msg_flags; /* flags on received message */
188};
189.Ed
190.Pp
191Here
192.Fa msg_name
193and
194.Fa msg_namelen
195specify the source address if the socket is unconnected;
196.Fa msg_name
197may be given as a null pointer if no names are desired or required.
198.Fa msg_iov
199and
200.Fa msg_iovlen
201describe scatter gather locations, as discussed in
202.Xr read 2 .
203.Fa msg_control ,
204which has length
205.Fa msg_controllen ,
206points to a buffer for other protocol control related messages
207or other miscellaneous ancillary data.
208The messages are of the form:
209.Bd -literal
210struct cmsghdr {
211 socklen_t cmsg_len; /* data byte count, including hdr */
212 int cmsg_level; /* originating protocol */
213 int cmsg_type; /* protocol-specific type */
214/* followed by u_char cmsg_data[]; */
215};
216.Ed
217.Pp
218See
219.Xr CMSG_DATA 3
220for how these messages are constructed and decomposed.
221.Pp
222Open file descriptors are now passed as ancillary data for
223.Dv AF_UNIX
224domain and
225.Xr socketpair 2
226sockets, with
227.Fa cmsg_level
228set to
229.Dv SOL_SOCKET
230and
231.Fa cmsg_type
232set to
233.Dv SCM_RIGHTS .
234.Pp
235The
236.Fa msg_flags
237field is set on return according to the message received.
238It will contain zero or more of the following values:
239.Pp
240.Bl -tag -width MSG_CTRUNC -offset indent -compact
241.It Dv MSG_OOB
242Returned to indicate that expedited or out-of-band data was received.
243.It Dv MSG_EOR
244Indicates end-of-record;
245the data returned completed a record (generally used with sockets of type
246.Dv SOCK_SEQPACKET ) .
247.It Dv MSG_TRUNC
248Indicates that
249the trailing portion of a datagram was discarded because the datagram
250was larger than the buffer supplied.
251.It Dv MSG_CTRUNC
252Indicates that some
253control data were discarded due to lack of space in the buffer
254for ancillary data.
255.It Dv MSG_BCAST
256Indicates that the packet was received as broadcast.
257.It Dv MSG_MCAST
258Indicates that the packet was received as multicast.
259.El
260.Pp
261The
262.Fn recvmmsg
263call uses an array of the
264.Fa mmsghdr
265structure of length
266.Fa vlen
267to group multiple
268.Fa msghdr
269structures into a single system call.
270.Fa vlen
271is capped at maximum
272.Dv 1024
273messages that are received in a single call.
274The
275.Fa flags
276field allows setting
277.Dv MSG_WAITFORONE
278to wait for one
279.Fa msghdr ,
280and set
281.Dv MSG_DONTWAIT
282for all subsequent messages.
283A provided
284.Fa timeout
285limits the time spent in the function but it does not limit the
286time spent in lower parts of the kernel.
287.Pp
288The
289.Fa mmsghdr
290structure has the following form, as defined in
291.In sys/socket.h :
292.Bd -literal
293struct mmsghdr {
294 struct msghdr msg_hdr;
295 unsigned int msg_len;
296};
297.Ed
298.Pp
299Here
300.Fa msg_len
301indicated the number of bytes received for each
302.Fa msg_hdr
303member.
304.Sh RETURN VALUES
305The
306.Fn recv ,
307.Fn recvfrom ,
308and
309.Fn recvmsg
310calls return the number of bytes received, or \-1 if an error occurred.
311The
312.Fn recvmmsg
313call returns the number of messages received, or \-1
314if an error occurred before the first message has been received.
315.Sh ERRORS
316.Fn recv ,
317.Fn recvfrom ,
318.Fn recvmsg ,
319and
320.Fn recvmmsg
321fail if:
322.Bl -tag -width "[EHOSTUNREACH]"
323.It Bq Er EBADF
324The argument
325.Fa s
326is an invalid descriptor.
327.It Bq Er ENOTCONN
328The socket is associated with a connection-oriented protocol
329and has not been connected (see
330.Xr connect 2
331and
332.Xr accept 2 ) .
333.It Bq Er ENOTSOCK
334The argument
335.Fa s
336does not refer to a socket.
337.It Bq Er EAGAIN
338The socket is marked non-blocking, and the receive operation
339would block, or
340a receive timeout had been set,
341and the timeout expired before data were received.
342.It Bq Er EINTR
343The receive was interrupted by delivery of a signal before
344any data were available.
345.It Bq Er EFAULT
346The receive buffer pointer(s) point outside the process's
347address space.
348.It Bq Er EHOSTUNREACH
349A socket operation was attempted to an unreachable host.
350.It Bq Er EHOSTDOWN
351A socket operation failed
352because the destination host was down.
353.It Bq Er ENETDOWN
354A socket operation encountered a dead network.
355.It Bq Er ECONNREFUSED
356The socket is associated with a connection-oriented protocol
357and the connection was forcefully rejected (see
358.Xr connect 2 ) .
359.El
360.Pp
361In addition,
362.Fn recv
363and
364.Fn recvfrom
365may return the following error:
366.Bl -tag -width Er
367.It Bq Er EINVAL
368.Fa len
369was larger than
370.Dv SSIZE_MAX .
371.El
372.Pp
373And
374.Fn recvmsg
375and
376.Fn recvmmsg
377may return one of the following errors:
378.Bl -tag -width Er
379.It Bq Er EINVAL
380The sum of the
381.Fa iov_len
382values in the
383.Fa msg_iov
384array overflowed an
385.Em ssize_t .
386.It Bq Er EMSGSIZE
387The
388.Fa msg_iovlen
389member of
390.Fa msg
391was less than 0 or larger than
392.Dv IOV_MAX .
393.It Bq Er EMSGSIZE
394The receiving program did not have sufficient
395free file descriptor slots.
396The descriptors are closed
397and any pending data can be returned
398by another call to
399.Fn recvmsg .
400.El
401.Sh SEE ALSO
402.Xr connect 2 ,
403.Xr fcntl 2 ,
404.Xr getsockopt 2 ,
405.Xr poll 2 ,
406.Xr read 2 ,
407.Xr select 2 ,
408.Xr socket 2 ,
409.Xr socketpair 2 ,
410.Xr CMSG_DATA 3 ,
411.Xr sockatmark 3
412.Sh STANDARDS
413The
414.Fn recv ,
415.Fn recvfrom ,
416and
417.Fn recvmsg
418functions conform to
419.St -p1003.1-2024 .
420The
421.Dv MSG_DONTWAIT ,
422.Dv MSG_BCAST ,
423and
424.Dv MSG_MCAST
425flags are extensions to that specification.
426.Sh HISTORY
427The
428.Fn recv
429function call appeared in
430.Bx 4.1c .
431The
432.Fn recvmmsg
433syscall first appeared in Linux 2.6.33 and was added to
434.Ox 7.2 .
435.Sh CAVEATS
436Calling
437.Fn recvmsg
438with a control message having no or an empty scatter/gather array
439exposes variations in implementations.
440To avoid these, always use an
441.Fa iovec
442with at least a one-byte buffer and set
443.Fa msg_iov
444and an
445.Fa msg_iovlen
446to use this vector.