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 strict
203 or C99 compilation mode.
206 flag sets MSG_DONTWAIT after the first message has been received.
207 This flag is only relevant for
214 structure to minimize the number of directly supplied arguments.
215 This structure has the following form, as defined in
219 void *msg_name; /* optional address */
220 socklen_t msg_namelen; /* size of address */
221 struct iovec *msg_iov; /* scatter/gather array */
222 int msg_iovlen; /* # elements in msg_iov */
223 void *msg_control; /* ancillary data, see below */
224 socklen_t msg_controllen;/* ancillary data buffer len */
225 int msg_flags; /* flags on received message */
233 specify the source address if the socket is unconnected;
235 may be given as a null pointer if no names are desired or required.
241 describe scatter gather locations, as discussed in
248 points to a buffer for other protocol control related messages
249 or other miscellaneous ancillary data.
250 The messages are of the form:
253 socklen_t cmsg_len; /* data byte count, including hdr */
254 int cmsg_level; /* originating protocol */
255 int cmsg_type; /* protocol-specific type */
257 u_char cmsg_data[]; */
261 As an example, one could use this to learn of changes in the data-stream
262 in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting
265 with no data buffer provided immediately after an
271 domain sockets, ancillary data can be used to pass file descriptors and
279 field is set on return according to the message received.
281 indicates end-of-record;
282 the data returned completed a record (generally used with sockets of type
283 .Dv SOCK_SEQPACKET ) .
286 the trailing portion of a datagram was discarded because the datagram
287 was larger than the buffer supplied.
290 control data were discarded due to lack of space in the buffer
293 is returned to indicate that expedited or out-of-band data were received.
299 structure, defined as follows in the
304 struct msghdr msg_hdr; /* message header */
305 ssize_t msg_len; /* message length */
309 On data reception the
311 field is updated to the length of the received message.
315 return the number of bytes received.
317 returns the number of messages received.
318 A value of -1 is returned if an error occurred.
325 is an invalid descriptor.
327 The remote socket end is forcibly closed.
329 The socket is associated with a connection-oriented protocol
330 and has not been connected (see
337 does not refer to a socket.
342 was used to receive rights (file descriptors) that were in flight on the
344 However, the receiving program did not have enough free file
345 descriptor slots to accept them.
346 In this case the descriptors are
347 closed, any pending data can be returned by another call to
350 The socket is marked non-blocking and the receive operation
352 a receive timeout had been set
353 and the timeout expired before data were received.
355 The receive was interrupted by delivery of a signal before
356 any data were available.
358 The receive buffer pointer(s) point outside the process's
projects / FreeBSD / FreeBSD.git / blob