| blob | 35ab5e9002384a40b57ec9a51b477bc28a38f141 |
1 .\" $NetBSD: recv.2,v 1.36 2013/07/14 14:29:09 njoly Exp $
2 .\"
3 .\" Copyright (c) 1983, 1990, 1991, 1993
4 .\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)recv.2 8.3 (Berkeley) 2/21/94
31 .\"
32 .Dd June 22, 2012
33 .Dt RECV 2
34 .Os
35 .Sh NAME
36 .Nm recv ,
37 .Nm recvfrom ,
38 .Nm recvmsg ,
39 .Nm recvmmsg
40 .Nd receive a message from a socket
41 .Sh LIBRARY
42 .Lb libc
43 .Sh SYNOPSIS
44 .In sys/socket.h
45 .Ft ssize_t
46 .Fn recv "int s" "void *buf" "size_t len" "int flags"
47 .Ft ssize_t
48 .Fn recvfrom "int s" "void * restrict buf" "size_t len" "int flags" "struct sockaddr * restrict from" "socklen_t * restrict fromlen"
49 .Ft ssize_t
50 .Fn recvmsg "int s" "struct msghdr *msg" "int flags"
51 .Ft int
52 .Fn recvmmsg "int s" "struct mmsghdr *mmsg" "unsigned int vlen" "unsigned int flags" "struct timespec *timeout"
53 .Sh DESCRIPTION
54 .Fn recvfrom ,
55 .Fn recvmsg
56 and
57 .Fn recvmmsg
58 are used to receive messages from a socket,
59 and may be used to receive data on a socket whether or not
60 it is connection-oriented.
61 .Pp
62 If
63 .Fa from
64 is non-nil, and the socket is not connection-oriented,
65 the source address of the message is filled in.
66 .Fa fromlen
67 is a value-result parameter, initialized to the size of
68 the buffer associated with
69 .Fa from ,
70 and modified on return to indicate the actual size of the
71 address stored there.
72 .Pp
73 The
74 .Fn recvmmsg
75 call be used to receive multiple messages in the same call using an array of
76 .Fa mmsghdr
77 elements with the following form, as defined in
78 .Ao Pa sys/socket.h Ac :
79 .Pp
80 .Bd -literal
81 struct mmsghdr {
82 struct msghdr msg_hdr; /* the message to be sent */
83 unsigned int msg_len; /* number of bytes received */
84 };
85 .Ed
86 .Pp
87 The
88 .Fa msg_len
89 member contains the number of bytes received for each
90 .Fa msg_hdr
91 member.
92 The array has
93 .Fa vlen
94 elements, which is limited to
95 .Dv 1024 .
96 If there is an error, a number fewer than
97 .Fa vlen
98 may be returned, and the error may be retrieved using
99 .Xr getsockopt 2
100 with
101 .Dv SO_ERROR .
102 If the flag
103 .Dv MSG_WAITFORONE
104 is set in
105 .Fa flags
106 then the
107 .Fn recvmmsg
108 call will wait for one message, and set
109 .Dv MSG_DONTWAIT
110 for the rest.
111 If the
112 .Fa timeout
113 parameter is not
114 .Dv NULL ,
115 then
116 .Fn recvmmsg
117 will return if that time is exceeded.
118 .Pp
119 The
120 .Fn recv
121 call is normally used only on a
122 .Em connected
123 socket (see
124 .Xr connect 2 )
125 and is identical to
126 .Fn recvfrom
127 with a nil
128 .Fa from
129 parameter.
130 As it is redundant, it may not be supported in future releases.
131 .Pp
132 .Fn recv ,
133 .Fn recvfrom
134 and
135 .Fn recvmsg
136 routines return the length of the message on successful
137 completion.
138 .Fn recvmmsg
139 returns the number of messages received.
140 If a message is too long to fit in the supplied buffer,
141 excess bytes may be discarded depending on the type of socket
142 the message is received from (see
143 .Xr socket 2 ) .
144 .Pp
145 If no messages are available at the socket, the
146 receive call waits for a message to arrive, unless
147 the socket is nonblocking (see
148 .Xr fcntl 2 )
149 in which case the value
150 \-1 is returned and the external variable
151 .Va errno
152 set to
153 .Er EAGAIN .
154 If no data is available and the remote peer was shut down,
155 0 is returned.
156 The receive calls normally return any data available,
157 up to the requested amount,
158 rather than waiting for receipt of the full amount requested;
159 this behavior is affected by the socket-level options
160 .Dv SO_RCVLOWAT
161 and
162 .Dv SO_RCVTIMEO
163 described in
164 .Xr getsockopt 2 .
165 .Pp
166 The
167 .Xr select 2
168 or
169 .Xr poll 2
170 call may be used to determine when more data arrive.
171 .Pp
172 The
173 .Fa flags
174 argument to a recv call is formed by
175 .Em or Ap ing
176 one or more of the values:
177 .Bl -column MSG_CMSG_CLOEXEC -offset indent
178 .It Dv MSG_CMSG_CLOEXEC Ta set the close on exec property for passed file descriptors
179 .It Dv MSG_OOB Ta process out-of-band data
180 .It Dv MSG_PEEK Ta peek at incoming message
181 .It Dv MSG_WAITALL Ta wait for full request or error
182 .El
183 The
184 .Dv MSG_OOB
185 flag requests receipt of out-of-band data
186 that would not be received in the normal data stream.
187 Some protocols place expedited data at the head of the normal
188 data queue, and thus this flag cannot be used with such protocols.
189 The
190 .Dv MSG_PEEK
191 flag causes the receive operation to return data
192 from the beginning of the receive queue without removing that
193 data from the queue.
194 Thus, a subsequent receive call will return the same data.
195 The
196 .Dv MSG_WAITALL
197 flag requests that the operation block until
198 the full request is satisfied.
199 However, the call may still return less data than requested
200 if a signal is caught, an error or disconnect occurs,
201 or the next data to be received is of a different type than that returned.
202 .Pp
203 The
204 .Fn recvmsg
205 call uses a
206 .Fa msghdr
207 structure to minimize the number of directly supplied parameters.
208 This structure has the following form, as defined in
209 .Ao Pa sys/socket.h Ac :
210 .Pp
211 .Bd -literal
212 struct msghdr {
213 void *msg_name; /* optional address */
214 socklen_t msg_namelen; /* size of address */
215 struct iovec *msg_iov; /* scatter/gather array */
216 int msg_iovlen; /* # elements in msg_iov */
217 void *msg_control; /* ancillary data, see below */
218 socklen_t msg_controllen; /* ancillary data buffer len */
219 int msg_flags; /* flags on received message */
220 };
221 .Ed
222 .Pp
223 Here
224 .Fa msg_name
225 and
226 .Fa msg_namelen
227 specify the source address if the socket is unconnected;
228 .Fa msg_name
229 may be given as a null pointer if no names are desired or required.
230 If the socket is connected,
231 .Fa msg_name
232 and
233 .Fa msg_namelen
234 are ignored.
235 .Fa msg_iov
236 and
237 .Fa msg_iovlen
238 describe scatter gather locations, as discussed in
239 .Xr read 2 .
240 .Fa msg_control ,
241 which has length
242 .Fa msg_controllen ,
243 points to a buffer for other protocol control related messages
244 or other miscellaneous ancillary data.
245 The messages are of the form:
246 .Bd -literal
247 struct cmsghdr {
248 socklen_t cmsg_len; /* data byte count, including hdr */
249 int cmsg_level; /* originating protocol */
250 int cmsg_type; /* protocol-specific type */
251 /* followed by
252 u_char cmsg_data[]; */
253 };
254 .Ed
255 As an example, one could use this to learn of changes in the data-stream
256 in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting
257 a recvmsg with no data buffer provided immediately after an
258 .Fn accept
259 call.
260 .Pp
261 Open file descriptors are now passed as ancillary data for
262 .Dv AF_LOCAL
263 domain sockets, with
264 .Fa cmsg_level
265 set to
266 .Dv SOL_SOCKET
267 and
268 .Fa cmsg_type
269 set to
270 .Dv SCM_RIGHTS .
271 .Pp
272 The
273 .Fa msg_flags
274 field is set on return according to the message received.
275 .Dv MSG_EOR
276 indicates end-of-record;
277 the data returned completed a record (generally used with sockets of type
278 .Dv SOCK_SEQPACKET ) .
279 .Dv MSG_TRUNC
280 indicates that
281 the trailing portion of a datagram was discarded because the datagram
282 was larger than the buffer supplied.
283 .Dv MSG_CTRUNC
284 indicates that some
285 control data were discarded due to lack of space in the buffer
286 for ancillary data.
287 .Dv MSG_OOB
288 is returned to indicate that expedited or out-of-band data were received.
289 .Sh RETURN VALUES
290 The
291 .Fn recv ,
292 .Fn recvfrom
293 and
294 .Fn recvmsg
295 calls return the number of bytes received, or \-1
296 if an error occurred.
297 For connected sockets whose remote peer was shut down,
298 0 is returned when no more data is available.
299 The
300 .Fn recvmmsg
301 calls return the number of messages received, or \-1
302 if an error occurred.
303 .Sh ERRORS
304 The calls fail if:
305 .Bl -tag -width Er
306 .It Bq Er EAGAIN
307 The socket is marked non-blocking, and the receive operation
308 would block, or
309 a receive timeout had been set,
310 and the timeout expired before data were received.
311 .It Bq Er EBADF
312 The argument
313 .Fa s
314 is an invalid descriptor.
315 .It Bq Er EFAULT
316 The receive buffer pointer(s) point outside the process's
317 address space.
318 .It Bq Er EINTR
319 The receive was interrupted by delivery of a signal before
320 any data were available.
321 .It Bq Er EINVAL
322 The total length of the I/O is more than can be expressed by the ssize_t
323 return value.
324 .It Bq Er ENOTCONN
325 The socket is associated with a connection-oriented protocol
326 and has not been connected (see
327 .Xr connect 2
328 and
329 .Xr accept 2 ) .
330 .It Bq Er ENOTSOCK
331 The argument
332 .Fa s
333 does not refer to a socket.
334 .El
335 .Pp
336 .Fn recvmsg
337 will also fail if:
338 .Bl -tag -width Er
339 .It Bq Er EMSGSIZE
340 The
341 .Fa msg_iovlen
342 member of the
343 .Fa msg
344 structure is less than or equal to 0
345 or is greater than
346 .Brq Dv IOV_MAX .
347 .El
348 .Sh SEE ALSO
349 .Xr fcntl 2 ,
350 .Xr getsockopt 2 ,
351 .Xr poll 2 ,
352 .Xr read 2 ,
353 .Xr select 2 ,
354 .Xr socket 2
355 .Sh HISTORY
356 The
357 .Fn recv
358 function call appeared in
359 .Bx 4.2 .
360 The
361 .Fn recvmmsg
362 function call appeared in
363 .Tn Linux 2.6.32
364 and
365 .Nx 7.0 .