Commit | Line | Data |
---|---|---|
931b8415 | 1 | .\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California. |
da268306 | 2 | .\" All rights reserved. |
03e70dcd | 3 | .\" |
af359dea C |
4 | .\" Redistribution and use in source and binary forms, with or without |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
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. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
da268306 | 19 | .\" |
af359dea C |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
03e70dcd | 31 | .\" |
af359dea C |
32 | .\" @(#)recv.2 6.11 (Berkeley) 5/1/91 |
33 | .\" | |
34 | .Dd May 1, 1991 | |
931b8415 | 35 | .Dt RECV 2 |
900dbb2d | 36 | .Os BSD 4.3r |
931b8415 CL |
37 | .Sh NAME |
38 | .Nm recv , | |
39 | .Nm recvfrom , | |
40 | .Nm recvmsg | |
41 | .Nd receive a message from a socket | |
42 | .Sh SYNOPSIS | |
43 | .Fd #include <sys/types.h> | |
44 | .Fd #include <sys/socket.h> | |
45 | .Ft int | |
af359dea | 46 | .Fn recv "int s" "void *buf" "int len" "int flags" |
931b8415 | 47 | .Ft int |
af359dea | 48 | .Fn recvfrom "int s" "void *buf" "int len" "int flags" "struct sockaddr *from" "int *fromlen" |
931b8415 CL |
49 | .Ft int |
50 | .Fn recvmsg "int s" "struct msghdr *msg" "int flags" | |
51 | .Sh DESCRIPTION | |
52 | .Fn Recvfrom | |
03e70dcd | 53 | and |
931b8415 | 54 | .Fn recvmsg |
c2643faf | 55 | are used to receive messages from a socket, |
900dbb2d MK |
56 | and may be used to receive data on a socket whether or not |
57 | it is connection-oriented. | |
931b8415 | 58 | .Pp |
03e70dcd | 59 | If |
931b8415 | 60 | .Fa from |
900dbb2d MK |
61 | is non-nil, and the socket is not connection-oriented, |
62 | the source address of the message is filled in. | |
931b8415 | 63 | .Fa Fromlen |
03e70dcd KM |
64 | is a value-result parameter, initialized to the size of |
65 | the buffer associated with | |
931b8415 | 66 | .Fa from , |
03e70dcd KM |
67 | and modified on return to indicate the actual size of the |
68 | address stored there. | |
931b8415 | 69 | .Pp |
c2643faf | 70 | The |
931b8415 | 71 | .Fn recv |
c2643faf | 72 | call is normally used only on a |
931b8415 | 73 | .Em connected |
c2643faf | 74 | socket (see |
931b8415 CL |
75 | .Xr connect 2 ) |
76 | and is identical to | |
77 | .Fn recvfrom | |
78 | with a nil | |
79 | .Fa from | |
c2643faf KS |
80 | parameter. |
81 | As it is redundant, it may not be supported in future releases. | |
931b8415 CL |
82 | .Pp |
83 | All three routines return the length of the message on successful | |
84 | completion. | |
03e70dcd KM |
85 | If a message is too long to fit in the supplied buffer, |
86 | excess bytes may be discarded depending on the type of socket | |
3e664f4b | 87 | the message is received from (see |
931b8415 CL |
88 | .Xr socket 2 ) . |
89 | .Pp | |
03e70dcd KM |
90 | If no messages are available at the socket, the |
91 | receive call waits for a message to arrive, unless | |
92 | the socket is nonblocking (see | |
900dbb2d | 93 | .Xr fcntl 2 ) |
931b8415 CL |
94 | in which case the value |
95 | -1 is returned and the external variable | |
96 | .Va errno | |
97 | set to | |
98 | .Er EWOULDBLOCK. | |
900dbb2d MK |
99 | The receive calls normally return any data available, |
100 | up to the requested amount, | |
101 | rather than waiting for receipt of the full amount requested; | |
102 | this behavior is affected by the socket-level options | |
103 | .Dv SO_RCVLOWAT | |
104 | and | |
105 | .Dv SO_RCVTIMEO | |
106 | described in | |
107 | .Xr getsockopt 2 . | |
931b8415 | 108 | .Pp |
03e70dcd | 109 | The |
931b8415 | 110 | .Xr select 2 |
900dbb2d | 111 | call may be used to determine when more data arrive. |
931b8415 | 112 | .Pp |
03e70dcd | 113 | The |
931b8415 | 114 | .Fa flags |
def9d0f9 | 115 | argument to a recv call is formed by |
931b8415 CL |
116 | .Em or Ap ing |
117 | one or more of the values: | |
900dbb2d MK |
118 | .Bl -column MSG_WAITALL -offset indent |
119 | .It Dv MSG_OOB Ta process out-of-band data | |
120 | .It Dv MSG_PEEK Ta peek at incoming message | |
121 | .It Dv MSG_WAITALL Ta wait for full request or error | |
122 | .El | |
123 | The | |
124 | .Dv MSG_OOB | |
125 | flag requests receipt of out-of-band data | |
126 | that would not be received in the normal data stream. | |
127 | Some protocols place expedited data at the head of the normal | |
128 | data queue, and thus this flag cannot be used with such protocols. | |
129 | The MSG_PEEK flag causes the receive operation to return data | |
130 | from the beginning of the receive queue without removing that | |
131 | data from the queue. | |
132 | Thus, a subsequent receive call will return the same data. | |
133 | The MSG_WAITALL flag requests that the operation block until | |
134 | the full request is satisfied. | |
135 | However, the call may still return less data than requested | |
136 | if a signal is caught, an error or disconnect occurs, | |
137 | or the next data to be received is of a different type than that returned. | |
931b8415 | 138 | .Pp |
03e70dcd | 139 | The |
931b8415 | 140 | .Fn recvmsg |
03e70dcd | 141 | call uses a |
931b8415 | 142 | .Fa msghdr |
03e70dcd KM |
143 | structure to minimize the number of directly supplied parameters. |
144 | This structure has the following form, as defined in | |
931b8415 CL |
145 | .Ao Pa sys/socket.h Ac : |
146 | .Pp | |
147 | .Bd -literal | |
03e70dcd | 148 | struct msghdr { |
c2643faf KS |
149 | caddr_t msg_name; /* optional address */ |
150 | u_int msg_namelen; /* size of address */ | |
151 | struct iovec *msg_iov; /* scatter/gather array */ | |
152 | u_int msg_iovlen; /* # elements in msg_iov */ | |
153 | caddr_t msg_control; /* ancillary data, see below */ | |
931b8415 CL |
154 | u_int msg_controllen; /* ancillary data buffer len */ |
155 | int msg_flags; /* flags on received message */ | |
03e70dcd | 156 | }; |
931b8415 CL |
157 | .Ed |
158 | .Pp | |
03e70dcd | 159 | Here |
931b8415 | 160 | .Fa msg_name |
03e70dcd | 161 | and |
931b8415 | 162 | .Fa msg_namelen |
03e70dcd | 163 | specify the destination address if the socket is unconnected; |
931b8415 | 164 | .Fa msg_name |
03e70dcd | 165 | may be given as a null pointer if no names are desired or required. |
931b8415 | 166 | .Fa Msg_iov |
03e70dcd | 167 | and |
931b8415 CL |
168 | .Fa msg_iovlen |
169 | describe scatter gather locations, as discussed in | |
170 | .Xr read 2 . | |
171 | .Fa Msg_control , | |
03e70dcd | 172 | which has length |
931b8415 CL |
173 | .Fa msg_controllen , |
174 | points to a buffer for other protocol control related messages | |
c2643faf KS |
175 | or other miscellaneous ancillary data. |
176 | The messages are of the form: | |
931b8415 | 177 | .Bd -literal |
c2643faf KS |
178 | struct cmsghdr { |
179 | u_int cmsg_len; /* data byte count, including hdr */ | |
180 | int cmsg_level; /* originating protocol */ | |
181 | int cmsg_type; /* protocol-specific type */ | |
182 | /* followed by | |
183 | u_char cmsg_data[]; */ | |
184 | }; | |
931b8415 | 185 | .Ed |
c2643faf KS |
186 | As an example, one could use this to learn of changes in the data-stream |
187 | in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting | |
900dbb2d MK |
188 | a recvmsg with no data buffer provided immediately after an |
189 | .Fn accept | |
190 | call. | |
931b8415 CL |
191 | .Pp |
192 | Open file descriptors are now passed as ancillary data for | |
193 | .Dv AF_UNIX | |
194 | domain sockets, with | |
195 | .Fa cmsg_level | |
900dbb2d | 196 | set to |
931b8415 CL |
197 | .Dv SOL_SOCKET |
198 | and | |
199 | .Fa cmsg_type | |
900dbb2d | 200 | set to |
931b8415 CL |
201 | .Dv SCM_RIGHTS . |
202 | .Pp | |
900dbb2d MK |
203 | The |
204 | .Fa msg_flags | |
205 | field is set on return according to the message received. | |
931b8415 | 206 | .Dv MSG_EOR |
900dbb2d MK |
207 | indicates end-of-record; |
208 | the data returned completed a record (generally used with sockets of type | |
209 | .Dv SOCK_SEQPACKET ) . | |
931b8415 CL |
210 | .Dv MSG_TRUNC |
211 | indicates that | |
900dbb2d MK |
212 | the trailing portion of a datagram was discarded because the datagram |
213 | was larger than the buffer supplied. | |
931b8415 CL |
214 | .Dv MSG_CTRUNC |
215 | indicates that some | |
900dbb2d MK |
216 | control data were discarded due to lack of space in the buffer |
217 | for ancillary data. | |
931b8415 | 218 | .Dv MSG_OOB |
900dbb2d | 219 | is returned to indicate that expedited or out-of-band data were received. |
931b8415 CL |
220 | .Pp |
221 | .Sh RETURN VALUES | |
222 | These calls return the number of bytes received, or -1 | |
03e70dcd | 223 | if an error occurred. |
931b8415 | 224 | .Sh ERRORS |
03e70dcd | 225 | The calls fail if: |
931b8415 CL |
226 | .Bl -tag -width EWOULDBLOCKAA |
227 | .It Bq Er EBADF | |
228 | The argument | |
229 | .Fa s | |
230 | is an invalid descriptor. | |
900dbb2d MK |
231 | .It Bq Er ENOTCONN |
232 | The socket is assoicated with a connection-oriented protocol | |
233 | and has not been connected (see | |
234 | .Xr connect 2 | |
235 | and | |
236 | .Xr accept 2 ). | |
931b8415 CL |
237 | .It Bq Er ENOTSOCK |
238 | The argument | |
239 | .Fa s | |
900dbb2d | 240 | does not refer to a socket. |
931b8415 | 241 | .It Bq Er EWOULDBLOCK |
900dbb2d MK |
242 | The socket is marked non-blocking, and the receive operation |
243 | would block, or | |
244 | a receive timeout had been set, | |
245 | and the timeout expired before data were received. | |
931b8415 | 246 | .It Bq Er EINTR |
03e70dcd | 247 | The receive was interrupted by delivery of a signal before |
900dbb2d | 248 | any data were available. |
931b8415 CL |
249 | .It Bq Er EFAULT |
250 | The receive buffer pointer(s) point outside the process's | |
251 | address space. | |
252 | .El | |
253 | .Sh SEE ALSO | |
254 | .Xr fcntl 2 , | |
255 | .Xr read 2 , | |
931b8415 CL |
256 | .Xr select 2 , |
257 | .Xr getsockopt 2 , | |
258 | .Xr socket 2 | |
259 | .Sh HISTORY | |
260 | The | |
261 | .Nm | |
262 | function call appeared in | |
263 | .Bx 4.2 . |