Commit | Line | Data |
---|---|---|
058811fd WJ |
1 | .\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
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. | |
19 | .\" | |
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. | |
31 | .\" | |
32 | .\" @(#)recv.2 6.11 (Berkeley) 5/1/91 | |
33 | .\" | |
34 | .Dd May 1, 1991 | |
35 | .Dt RECV 2 | |
36 | .Os BSD 4.3r | |
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 | |
46 | .Fn recv "int s" "void *buf" "int len" "int flags" | |
47 | .Ft int | |
48 | .Fn recvfrom "int s" "void *buf" "int len" "int flags" "struct sockaddr *from" "int *fromlen" | |
49 | .Ft int | |
50 | .Fn recvmsg "int s" "struct msghdr *msg" "int flags" | |
51 | .Sh DESCRIPTION | |
52 | .Fn Recvfrom | |
53 | and | |
54 | .Fn recvmsg | |
55 | are used to receive messages from a socket, | |
56 | and may be used to receive data on a socket whether or not | |
57 | it is connection-oriented. | |
58 | .Pp | |
59 | If | |
60 | .Fa from | |
61 | is non-nil, and the socket is not connection-oriented, | |
62 | the source address of the message is filled in. | |
63 | .Fa Fromlen | |
64 | is a value-result parameter, initialized to the size of | |
65 | the buffer associated with | |
66 | .Fa from , | |
67 | and modified on return to indicate the actual size of the | |
68 | address stored there. | |
69 | .Pp | |
70 | The | |
71 | .Fn recv | |
72 | call is normally used only on a | |
73 | .Em connected | |
74 | socket (see | |
75 | .Xr connect 2 ) | |
76 | and is identical to | |
77 | .Fn recvfrom | |
78 | with a nil | |
79 | .Fa from | |
80 | parameter. | |
81 | As it is redundant, it may not be supported in future releases. | |
82 | .Pp | |
83 | All three routines return the length of the message on successful | |
84 | completion. | |
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 | |
87 | the message is received from (see | |
88 | .Xr socket 2 ) . | |
89 | .Pp | |
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 | |
93 | .Xr fcntl 2 ) | |
94 | in which case the value | |
95 | -1 is returned and the external variable | |
96 | .Va errno | |
97 | set to | |
98 | .Er EWOULDBLOCK. | |
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 . | |
108 | .Pp | |
109 | The | |
110 | .Xr select 2 | |
111 | call may be used to determine when more data arrive. | |
112 | .Pp | |
113 | The | |
114 | .Fa flags | |
115 | argument to a recv call is formed by | |
116 | .Em or Ap ing | |
117 | one or more of the values: | |
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. | |
138 | .Pp | |
139 | The | |
140 | .Fn recvmsg | |
141 | call uses a | |
142 | .Fa msghdr | |
143 | structure to minimize the number of directly supplied parameters. | |
144 | This structure has the following form, as defined in | |
145 | .Ao Pa sys/socket.h Ac : | |
146 | .Pp | |
147 | .Bd -literal | |
148 | struct msghdr { | |
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 */ | |
154 | u_int msg_controllen; /* ancillary data buffer len */ | |
155 | int msg_flags; /* flags on received message */ | |
156 | }; | |
157 | .Ed | |
158 | .Pp | |
159 | Here | |
160 | .Fa msg_name | |
161 | and | |
162 | .Fa msg_namelen | |
163 | specify the destination address if the socket is unconnected; | |
164 | .Fa msg_name | |
165 | may be given as a null pointer if no names are desired or required. | |
166 | .Fa Msg_iov | |
167 | and | |
168 | .Fa msg_iovlen | |
169 | describe scatter gather locations, as discussed in | |
170 | .Xr read 2 . | |
171 | .Fa Msg_control , | |
172 | which has length | |
173 | .Fa msg_controllen , | |
174 | points to a buffer for other protocol control related messages | |
175 | or other miscellaneous ancillary data. | |
176 | The messages are of the form: | |
177 | .Bd -literal | |
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 | }; | |
185 | .Ed | |
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 | |
188 | a recvmsg with no data buffer provided immediately after an | |
189 | .Fn accept | |
190 | call. | |
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 | |
196 | set to | |
197 | .Dv SOL_SOCKET | |
198 | and | |
199 | .Fa cmsg_type | |
200 | set to | |
201 | .Dv SCM_RIGHTS . | |
202 | .Pp | |
203 | The | |
204 | .Fa msg_flags | |
205 | field is set on return according to the message received. | |
206 | .Dv MSG_EOR | |
207 | indicates end-of-record; | |
208 | the data returned completed a record (generally used with sockets of type | |
209 | .Dv SOCK_SEQPACKET ) . | |
210 | .Dv MSG_TRUNC | |
211 | indicates that | |
212 | the trailing portion of a datagram was discarded because the datagram | |
213 | was larger than the buffer supplied. | |
214 | .Dv MSG_CTRUNC | |
215 | indicates that some | |
216 | control data were discarded due to lack of space in the buffer | |
217 | for ancillary data. | |
218 | .Dv MSG_OOB | |
219 | is returned to indicate that expedited or out-of-band data were received. | |
220 | .Pp | |
221 | .Sh RETURN VALUES | |
222 | These calls return the number of bytes received, or -1 | |
223 | if an error occurred. | |
224 | .Sh ERRORS | |
225 | The calls fail if: | |
226 | .Bl -tag -width EWOULDBLOCKAA | |
227 | .It Bq Er EBADF | |
228 | The argument | |
229 | .Fa s | |
230 | is an invalid descriptor. | |
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 ). | |
237 | .It Bq Er ENOTSOCK | |
238 | The argument | |
239 | .Fa s | |
240 | does not refer to a socket. | |
241 | .It Bq Er EWOULDBLOCK | |
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. | |
246 | .It Bq Er EINTR | |
247 | The receive was interrupted by delivery of a signal before | |
248 | any data were available. | |
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 , | |
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 . |