1 .\" Copyright (c) 1983, 1990, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" @(#)recv.2 8.3 (Berkeley) 2/21/94
39 .Nd receive message(s) from a socket
45 .Fn recv "int s" "void *buf" "size_t len" "int flags"
47 .Fn recvfrom "int s" "void *buf" "size_t len" "int flags" "struct sockaddr * restrict from" "socklen_t * restrict fromlen"
49 .Fn recvmsg "int s" "struct msghdr *msg" "int flags"
51 .Fn recvmmsg "int s" "struct mmsghdr * restrict msgvec" "size_t vlen" "int flags" "const struct timespec * restrict timeout"
59 are used to receive messages from a socket,
60 and may be used to receive data on a socket whether or not
61 it is connection-oriented.
66 and the socket is not connection-oriented,
67 the source address of the message is filled in.
71 is a value-result argument, initialized to the size of
72 the buffer associated with
74 and modified on return to indicate the actual size of the
79 function is normally used only on a
86 null pointer passed as its
92 function is used to receive multiple
94 Their number is supplied by
96 The messages are placed in the buffers described by
98 vector, after reception.
99 The size of each received message is placed in the
101 field of each element of the vector.
104 is NULL the call blocks until the data is available for each
105 supplied message buffer.
106 Otherwise it waits for data for the specified amount of time.
107 If the timeout expired and there is no data received,
108 a value 0 is returned.
111 system call is used to implement the timeout mechanism,
112 before first receive is performed.
119 return the length of the message on successful
122 returns the number of received messages.
123 If a message is too long to fit in the supplied buffer,
124 excess bytes may be discarded depending on the type of socket
125 the message is received from (see
128 If no messages are available at the socket, the
129 receive call waits for a message to arrive, unless
130 the socket is non-blocking (see
132 in which case the value
133 \-1 is returned and the global variable
137 The receive calls except
139 normally return any data available,
140 up to the requested amount,
141 rather than waiting for receipt of the full amount requested;
142 this behavior is affected by the socket-level options
150 function implements this behaviour for each message in the vector.
154 system call may be used to determine when more data arrives.
160 function is formed by
162 one or more of the values:
163 .Bl -column ".Dv MSG_CMSG_CLOEXEC" -offset indent
164 .It Dv MSG_OOB Ta process out-of-band data
165 .It Dv MSG_PEEK Ta peek at incoming message
166 .It Dv MSG_WAITALL Ta wait for full request or error
167 .It Dv MSG_DONTWAIT Ta do not block
168 .It Dv MSG_CMSG_CLOEXEC Ta set received fds close-on-exec
169 .It Dv MSG_WAITFORONE Ta do not block after receiving the first message
177 flag requests receipt of out-of-band data
178 that would not be received in the normal data stream.
179 Some protocols place expedited data at the head of the normal
180 data queue, and thus this flag cannot be used with such protocols.
183 flag causes the receive operation to return data
184 from the beginning of the receive queue without removing that
186 Thus, a subsequent receive call will return the same data.
189 flag requests that the operation block until
190 the full request is satisfied.
191 However, the call may still return less data than requested
192 if a signal is caught, an error or disconnect occurs,
193 or the next data to be received is of a different type than that returned.
196 flag requests the call to return when it would block otherwise.
197 If no data is available,
201 This flag is not available in
208 flag sets MSG_DONTWAIT after the first message has been received.
209 This flag is only relevant for
216 structure to minimize the number of directly supplied arguments.
217 This structure has the following form, as defined in
221 void *msg_name; /* optional address */
222 socklen_t msg_namelen; /* size of address */
223 struct iovec *msg_iov; /* scatter/gather array */
224 int msg_iovlen; /* # elements in msg_iov */
225 void *msg_control; /* ancillary data, see below */
226 socklen_t msg_controllen;/* ancillary data buffer len */
227 int msg_flags; /* flags on received message */
235 specify the source address if the socket is unconnected;
237 may be given as a null pointer if no names are desired or required.
243 describe scatter gather locations, as discussed in
250 points to a buffer for other protocol control related messages
251 or other miscellaneous ancillary data.
252 The messages are of the form:
255 socklen_t cmsg_len; /* data byte count, including hdr */
256 int cmsg_level; /* originating protocol */
257 int cmsg_type; /* protocol-specific type */
259 u_char cmsg_data[]; */
263 As an example, one could use this to learn of changes in the data-stream
264 in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting
267 with no data buffer provided immediately after an
273 domain sockets, ancillary data can be used to pass file descriptors and
281 field is set on return according to the message received.
283 indicates end-of-record;
284 the data returned completed a record (generally used with sockets of type
285 .Dv SOCK_SEQPACKET ) .
288 the trailing portion of a datagram was discarded because the datagram
289 was larger than the buffer supplied.
292 control data were discarded due to lack of space in the buffer
295 is returned to indicate that expedited or out-of-band data were received.
301 structure, defined as follows in the
306 struct msghdr msg_hdr; /* message header */
307 ssize_t msg_len; /* message length */
311 On data reception the
313 field is updated to the length of the received message.
317 return the number of bytes received.
319 returns the number of messages received.
320 A value of -1 is returned if an error occurred.
327 is an invalid descriptor.
329 The remote socket end is forcibly closed.
331 The socket is associated with a connection-oriented protocol
332 and has not been connected (see
339 does not refer to a socket.
344 was used to receive rights (file descriptors) that were in flight on the
346 However, the receiving program did not have enough free file
347 descriptor slots to accept them.
348 In this case the descriptors are
349 closed, any pending data can be returned by another call to
352 The socket is marked non-blocking and the receive operation
354 a receive timeout had been set
355 and the timeout expired before data were received.
357 The receive was interrupted by delivery of a signal before
358 any data were available.
360 The receive buffer pointer(s) point outside the process's
projects / FreeBSD / FreeBSD.git / blob