Debian Codegraph @

upstream/debian-unstable/man2/recv.2

raw
1 .\" Copyright 1983-1991, The Regents of the University of California.
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
5 .\"
6 .TH recv 2 2025-10-29 "Linux man-pages 6.18"
7 .SH NAME
8 recv, recvfrom, recvmsg \- receive a message from a socket
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <sys/socket.h>
15 .P
16 .BR "ssize_t recv(" "size_t size;"
17 .BI " int " sockfd ", void " buf [ size "], size_t " size ,
18 .BI " int " flags );
19 .BR "ssize_t recvfrom(" "size_t size;"
20 .BI " int " sockfd ", void " buf "[restrict " size "], size_t " size ,
21 .BI " int " flags ,
22 .BI " struct sockaddr *_Nullable restrict " src_addr ,
23 .BI " socklen_t *_Nullable restrict " addrlen );
24 .BI "ssize_t recvmsg(int " sockfd ", struct msghdr *" msg ", int " flags );
25 .fi
26 .SH DESCRIPTION
27 The
28 .BR recv (),
29 .BR recvfrom (),
30 and
31 .BR recvmsg ()
32 calls are used to receive messages from a socket.
33 They may be used
34 to receive data on both connectionless and connection-oriented sockets.
35 This page first describes common features of all three system calls,
36 and then describes the differences between the calls.
37 .P
38 The only difference between
39 .BR recv ()
40 and
41 .BR read (2)
42 is the presence of
43 .IR flags .
44 With a zero
45 .I flags
46 argument,
47 .BR recv ()
48 is generally equivalent to
49 .BR read (2)
50 (but see NOTES).
51 Also, the following call
52 .P
53 .in +4n
54 .EX
55 recv(sockfd, buf, size, flags);
56 .EE
57 .in
58 .P
59 is equivalent to
60 .P
61 .in +4n
62 .EX
63 recvfrom(sockfd, buf, size, flags, NULL, NULL);
64 .EE
65 .in
66 .P
67 All three calls return the size of the message on successful
68 completion.
69 If a message is too long to fit in the supplied buffer, excess
70 bytes may be discarded depending on the type of socket the message is
71 received from.
72 .P
73 If no messages are available at the socket, the receive calls wait for a
74 message to arrive, unless the socket is nonblocking (see
75 .BR fcntl (2)),
76 in which case the value \-1 is returned and
77 .I errno
78 is set to
79 .BR EAGAIN " or " EWOULDBLOCK .
80 The receive calls normally return any data available, up to the requested
81 amount, rather than waiting for receipt of the full amount requested.
82 .P
83 An application can use
84 .BR select (2),
85 .BR poll (2),
86 or
87 .BR epoll (7)
88 to determine when more data arrives on a socket.
89 .SS The flags argument
90 The
91 .I flags
92 argument is formed by ORing one or more of the following values:
93 .TP
94 .BR MSG_CMSG_CLOEXEC " (" recvmsg "() only; since Linux 2.6.23)"
95 Set the close-on-exec flag for the file descriptor received
96 via a UNIX domain file descriptor using the
97 .B SCM_RIGHTS
98 operation (described in
99 .BR unix (7)).
100 This flag is useful for the same reasons as the
101 .B O_CLOEXEC
102 flag of
103 .BR open (2).
104 .TP
105 .BR MSG_DONTWAIT " (since Linux 2.2)"
106 Enables nonblocking operation;
107 if the operation would block,
108 the call fails with
109 .B EAGAIN
110 or
111 .BR EWOULDBLOCK .
112 This provides similar behavior to setting the
113 .B O_NONBLOCK
114 flag (via the
115 .BR fcntl (2)
116 .B F_SETFL
117 operation), but differs in that
118 .B MSG_DONTWAIT
119 is a per-call option, whereas
120 .B O_NONBLOCK
121 is a setting on the open file description (see
122 .BR open (2)),
123 which will affect all threads in the calling process
124 as well as other processes that hold file descriptors
125 referring to the same open file description.
126 .TP
127 .BR MSG_ERRQUEUE " (since Linux 2.2)"
128 This flag
129 specifies that queued errors should be received from the socket error queue.
130 The error is passed in
131 an ancillary message with a type dependent on the protocol (for IPv4
132 .BR IP_RECVERR ).
133 The user should supply a buffer of sufficient size.
134 See
135 .BR cmsg (3)
136 and
137 .BR ip (7)
138 for more information.
139 The payload of the original packet that caused the error
140 is passed as normal data via
141 .IR msg_iovec .
142 The original destination address of the datagram that caused the error
143 is supplied via
144 .IR msg_name .
145 .IP
146 The error is supplied in a
147 .I sock_extended_err
148 structure:
149 .IP
150 .in +4n
151 .EX
152 #define SO_EE_ORIGIN_NONE 0
153 #define SO_EE_ORIGIN_LOCAL 1
154 #define SO_EE_ORIGIN_ICMP 2
155 #define SO_EE_ORIGIN_ICMP6 3
156 \&
157 struct sock_extended_err
158 {
159 uint32_t ee_errno; /* Error number */
160 uint8_t ee_origin; /* Where the error originated */
161 uint8_t ee_type; /* Type */
162 uint8_t ee_code; /* Code */
163 uint8_t ee_pad; /* Padding */
164 uint32_t ee_info; /* Additional information */
165 uint32_t ee_data; /* Other data */
166 /* More data may follow */
167 };
168 \&
169 struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);
170 .EE
171 .in
172 .IP
173 .I ee_errno
174 contains the
175 .I errno
176 number of the queued error.
177 .I ee_origin
178 is the origin code of where the error originated.
179 The other fields are protocol-specific.
180 The macro
181 .B SO_EE_OFFENDER
182 returns a pointer to the address of the network object
183 where the error originated from given a pointer to the ancillary message.
184 If this address is not known, the
185 .I sa_family
186 member of the
187 .I sockaddr
188 contains
189 .B AF_UNSPEC
190 and the other fields of the
191 .I sockaddr
192 are undefined.
193 The payload of the packet that caused the error is passed as normal data.
194 .IP
195 For local errors, no address is passed (this
196 can be checked with the
197 .I cmsg_len
198 member of the
199 .IR cmsghdr ).
200 For error receives,
201 the
202 .B MSG_ERRQUEUE
203 flag is set in the
204 .IR msghdr .
205 After an error has been passed, the pending socket error
206 is regenerated based on the next queued error and will be passed
207 on the next socket operation.
208 .TP
209 .B MSG_OOB
210 This flag requests receipt of out-of-band data that would not be received
211 in the normal data stream.
212 Some protocols place expedited data
213 at the head of the normal data queue, and thus this flag cannot
214 be used with such protocols.
215 .TP
216 .B MSG_PEEK
217 This flag causes the receive operation to
218 return data from the beginning of the
219 receive queue without removing that data from the queue.
220 Thus, a
221 subsequent receive call will return the same data.
222 .TP
223 .BR MSG_TRUNC " (since Linux 2.2)"
224 For raw
225 .RB ( AF_PACKET ),
226 Internet datagram (since Linux 2.4.27/2.6.8),
227 netlink (since Linux 2.6.22),
228 and UNIX datagram as well as sequenced-packet
229 .\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f
230 (since Linux 3.4) sockets:
231 return the real size of the packet or datagram,
232 even when it was longer than the passed buffer.
233 .IP
234 For use with Internet stream sockets, see
235 .BR tcp (7).
236 .TP
237 .BR MSG_WAITALL " (since Linux 2.2)"
238 This flag requests that the operation block until the full request is
239 satisfied.
240 However, the call may still return less data than requested if
241 a signal is caught, an error or disconnect occurs, or the next data to be
242 received is of a different type than that returned.
243 This flag has no effect for datagram sockets.
244 .\"
245 .SS recvfrom()
246 .BR recvfrom ()
247 places the received message into the buffer
248 .IR buf .
249 The caller must specify the size of the buffer in
250 .IR size .
251 .P
252 If
253 .I src_addr
254 is not NULL,
255 and the underlying protocol provides the source address of the message,
256 that source address is placed in the buffer pointed to by
257 .IR src_addr .
258 .\" (Note: for datagram sockets in both the UNIX and Internet domains,
259 .\" .I src_addr
260 .\" is filled in.
261 .\" .I src_addr
262 .\" is also filled in for stream sockets in the UNIX domain, but is not
263 .\" filled in for stream sockets in the Internet domain.)
264 .\" [The above notes on AF_UNIX and AF_INET sockets apply as at
265 .\" Kernel 2.4.18. (MTK, 22 Jul 02)]
266 In this case,
267 .I addrlen
268 is a value-result argument.
269 Before the call,
270 it should be initialized to the size of the buffer associated with
271 .IR src_addr .
272 Upon return,
273 .I addrlen
274 is updated to contain the actual size of the source address.
275 The returned address is truncated if the buffer provided is too small;
276 in this case,
277 .I addrlen
278 will return a value greater than was supplied to the call.
279 .P
280 If the caller is not interested in the source address,
281 .I src_addr
282 and
283 .I addrlen
284 should be specified as NULL.
285 .\"
286 .SS recv()
287 The
288 .BR recv ()
289 call is normally used only on a
290 .I connected
291 socket (see
292 .BR connect (2)).
293 It is equivalent to the call:
294 .P
295 .in +4n
296 .EX
297 recvfrom(fd, buf, size, flags, NULL, NULL);
298 .EE
299 .in
300 .\"
301 .SS recvmsg()
302 The
303 .BR recvmsg ()
304 call uses a
305 .I msghdr
306 structure to minimize the number of directly supplied arguments.
307 This structure is defined as follows in
308 .IR <sys/socket.h> :
309 .P
310 .in +4n
311 .EX
312 struct msghdr {
313 void *msg_name; /* Optional address */
314 socklen_t msg_namelen; /* Size of address */
315 struct iovec *msg_iov; /* Scatter/gather array */
316 size_t msg_iovlen; /* # elements in msg_iov */
317 void *msg_control; /* Ancillary data, see below */
318 size_t msg_controllen; /* Ancillary data buffer size */
319 int msg_flags; /* Flags on received message */
320 };
321 .EE
322 .in
323 .P
324 The
325 .I msg_name
326 field points to a caller-allocated buffer that is used to
327 return the source address if the socket is unconnected.
328 The caller should set
329 .I msg_namelen
330 to the size of this buffer before this call;
331 upon return from a successful call,
332 .I msg_namelen
333 will contain the size of the returned address.
334 If the application does not need to know the source address,
335 .I msg_name
336 can be specified as NULL.
337 .P
338 The fields
339 .I msg_iov
340 and
341 .I msg_iovlen
342 describe scatter-gather locations, as discussed in
343 .BR readv (2).
344 .P
345 The field
346 .IR msg_control ,
347 which has size
348 .IR msg_controllen ,
349 points to a buffer for other protocol control-related messages or
350 miscellaneous ancillary data.
351 When
352 .BR recvmsg ()
353 is called,
354 .I msg_controllen
355 should contain the size of the available buffer in
356 .IR msg_control ;
357 upon return from a successful call it will contain the size
358 of the control message sequence.
359 .P
360 The messages are of the form:
361 .P
362 .in +4n
363 .EX
364 struct cmsghdr {
365 size_t cmsg_len; /* Data byte count, including header
366 (type is socklen_t in POSIX) */
367 int cmsg_level; /* Originating protocol */
368 int cmsg_type; /* Protocol\-specific type */
369 /* followed by
370 unsigned char cmsg_data[]; */
371 };
372 .EE
373 .in
374 .P
375 Ancillary data should be accessed only by the macros defined in
376 .BR cmsg (3).
377 .P
378 As an example, Linux uses this ancillary data mechanism to pass extended
379 errors, IP options, or file descriptors over UNIX domain sockets.
380 For further information on the use of ancillary data in various
381 socket domains, see
382 .BR unix (7)
383 and
384 .BR ip (7).
385 .P
386 The
387 .I msg_flags
388 field in the
389 .I msghdr
390 is set on return of
391 .BR recvmsg ().
392 It can contain several flags:
393 .TP
394 .B MSG_EOR
395 indicates end-of-record;
396 the data returned completed a record
397 (generally, used with sockets of type
398 .BR SOCK_SEQPACKET ).
399 .TP
400 .B MSG_TRUNC
401 indicates that the trailing portion of a datagram was discarded because the
402 datagram was larger than the buffer supplied.
403 .TP
404 .B MSG_CTRUNC
405 indicates that some control data was discarded due to lack of space in the
406 buffer for ancillary data.
407 .TP
408 .B MSG_OOB
409 is returned to indicate that expedited or out-of-band data was received.
410 .TP
411 .B MSG_ERRQUEUE
412 indicates that no data was received but an extended error from the socket
413 error queue.
414 .TP
415 .BR MSG_CMSG_CLOEXEC " (since Linux 2.6.23)"
416 .\" commit 4a19542e5f694cd408a32c3d9dc593ba9366e2d7
417 indicates that
418 .B MSG_CMSG_CLOEXEC
419 was specified in the
420 .I flags
421 argument of
422 .BR recvmsg ().
423 .SH RETURN VALUE
424 These calls return the number of bytes received, or \-1
425 if an error occurred.
426 In the event of an error,
427 .I errno
428 is set to indicate the error.
429 .P
430 When a stream socket peer has performed an orderly shutdown,
431 the return value will be 0 (the traditional "end-of-file" return).
432 .P
433 Datagram sockets in various domains (e.g., the UNIX and Internet domains)
434 permit zero-size datagrams.
435 When such a datagram is received, the return value is 0.
436 .P
437 The value 0 may also be returned if the requested number of bytes
438 to receive from a stream socket was 0.
439 .SH ERRORS
440 These are some standard errors generated by the socket layer.
441 Additional errors
442 may be generated and returned from the underlying protocol modules;
443 see their manual pages.
444 .TP
445 .BR EAGAIN " or " EWOULDBLOCK
446 .\" Actually EAGAIN on Linux
447 The socket is marked nonblocking and the receive operation
448 would block, or a receive timeout had been set and the timeout expired
449 before data was received.
450 POSIX.1 allows either error to be returned for this case,
451 and does not require these constants to have the same value,
452 so a portable application should check for both possibilities.
453 .TP
454 .B EBADF
455 The argument
456 .I sockfd
457 is an invalid file descriptor.
458 .TP
459 .B ECONNREFUSED
460 A remote host refused to allow the network connection (typically
461 because it is not running the requested service).
462 .TP
463 .B EFAULT
464 The receive buffer pointer(s) point outside the process's
465 address space.
466 .TP
467 .B EINTR
468 The receive was interrupted by delivery of a signal
469 before any data was available;
470 see
471 .BR signal (7).
472 .TP
473 .B EINVAL
474 Invalid argument passed.
475 .\" e.g., msg_namelen < 0 for recvmsg() or addrlen < 0 for recvfrom()
476 .TP
477 .B ENOMEM
478 Could not allocate memory for
479 .BR recvmsg ().
480 .TP
481 .B ENOTCONN
482 The socket is associated with a connection-oriented protocol
483 and has not been connected (see
484 .BR connect (2)
485 and
486 .BR accept (2)).
487 .TP
488 .B ENOTSOCK
489 The file descriptor
490 .I sockfd
491 does not refer to a socket.
492 .SH VERSIONS
493 According to POSIX.1,
494 .\" POSIX.1-2001, POSIX.1-2008
495 the
496 .I msg_controllen
497 field of the
498 .I msghdr
499 structure should be typed as
500 .IR socklen_t ,
501 and the
502 .I msg_iovlen
503 field should be typed as
504 .IR int ,
505 but glibc currently types both as
506 .IR size_t .
507 .\" glibc bug for msg_controllen raised 12 Mar 2006
508 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448
509 .\" The problem is an underlying kernel issue: the size of the
510 .\" __kernel_size_t type used to type these fields varies
511 .\" across architectures, but socklen_t is always 32 bits,
512 .\" as (at least with GCC) is int.
513 .SH STANDARDS
514 POSIX.1-2024.
515 .SH HISTORY
516 POSIX.1-2001,
517 4.2BSD.
518 .P
519 POSIX.1 describes only the
520 .BR MSG_OOB ,
521 .BR MSG_PEEK ,
522 and
523 .B MSG_WAITALL
524 flags.
525 .SH NOTES
526 If a zero-size datagram is pending,
527 .BR read (2)
528 and
529 .BR recv ()
530 with a
531 .I flags
532 argument of zero provide different behavior.
533 In this circumstance,
534 .BR read (2)
535 has no effect (the datagram remains pending), while
536 .BR recv ()
537 consumes the pending datagram.
538 .P
539 See
540 .BR recvmmsg (2)
541 for information about a Linux-specific system call
542 that can be used to receive multiple datagrams in a single call.
543 .SH EXAMPLES
544 An example of the use of
545 .BR recvfrom ()
546 is shown in
547 .BR getaddrinfo (3).
548 .SH SEE ALSO
549 .BR fcntl (2),
550 .BR getsockopt (2),
551 .BR read (2),
552 .BR recvmmsg (2),
553 .BR select (2),
554 .BR shutdown (2),
555 .BR socket (2),
556 .BR cmsg (3),
557 .BR sockatmark (3),
558 .BR ip (7),
559 .BR ipv6 (7),
560 .BR socket (7),
561 .BR tcp (7),
562 .BR udp (7),
563 .BR unix (7)