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