Commit | Line | Data |
---|---|---|
03e70dcd KM |
1 | .\" Copyright (c) 1983 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
758e5b44 | 5 | .\" @(#)recv.2 6.5 (Berkeley) %G% |
03e70dcd | 6 | .\" |
a9e7c426 | 7 | .TH RECV 2 "" |
03e70dcd KM |
8 | .UC 5 |
9 | .SH NAME | |
10 | recv, recvfrom, recvmsg \- receive a message from a socket | |
11 | .SH SYNOPSIS | |
12 | .nf | |
13 | .ft B | |
14 | #include <sys/types.h> | |
15 | #include <sys/socket.h> | |
16 | .PP | |
17 | .ft B | |
18 | cc = recv(s, buf, len, flags) | |
19 | int cc, s; | |
20 | char *buf; | |
21 | int len, flags; | |
22 | .PP | |
23 | .ft B | |
24 | cc = recvfrom(s, buf, len, flags, from, fromlen) | |
25 | int cc, s; | |
26 | char *buf; | |
27 | int len, flags; | |
28 | struct sockaddr *from; | |
29 | int *fromlen; | |
30 | .PP | |
31 | .ft B | |
32 | cc = recvmsg(s, msg, flags) | |
33 | int cc, s; | |
fc04ceb7 | 34 | struct msghdr *msg; |
03e70dcd KM |
35 | int flags; |
36 | .ft R | |
37 | .SH DESCRIPTION | |
38 | .IR Recv , | |
39 | .IR recvfrom , | |
40 | and | |
41 | .IR recvmsg | |
42 | are used to receive messages from a socket. | |
43 | .PP | |
44 | The | |
45 | .I recv | |
def9d0f9 | 46 | call is normally used only on a |
03e70dcd KM |
47 | .I connected |
48 | socket (see | |
49 | .IR connect (2)), | |
50 | while | |
51 | .I recvfrom | |
52 | and | |
53 | .I recvmsg | |
54 | may be used to receive data on a socket whether | |
55 | it is in a connected state or not. | |
56 | .PP | |
57 | If | |
58 | .I from | |
59 | is non-zero, the source address of the message is filled in. | |
60 | .I Fromlen | |
61 | is a value-result parameter, initialized to the size of | |
62 | the buffer associated with | |
63 | .IR from , | |
64 | and modified on return to indicate the actual size of the | |
65 | address stored there. | |
66 | The length of the message is returned in | |
67 | .IR cc . | |
68 | If a message is too long to fit in the supplied buffer, | |
69 | excess bytes may be discarded depending on the type of socket | |
3e664f4b KD |
70 | the message is received from (see |
71 | .IR socket (2)). | |
03e70dcd KM |
72 | .PP |
73 | If no messages are available at the socket, the | |
74 | receive call waits for a message to arrive, unless | |
75 | the socket is nonblocking (see | |
76 | .IR ioctl (2)) | |
77 | in which case a | |
78 | .I cc | |
79 | of \-1 is returned with the external variable errno | |
80 | set to EWOULDBLOCK. | |
81 | .PP | |
82 | The | |
83 | .IR select (2) | |
84 | call may be used to determine when more data arrives. | |
85 | .PP | |
86 | The | |
87 | .I flags | |
def9d0f9 | 88 | argument to a recv call is formed by |
03e70dcd KM |
89 | .IR or 'ing |
90 | one or more of the values, | |
91 | .PP | |
92 | .nf | |
93 | .RS | |
def9d0f9 | 94 | .ta \w'#define\ \ 'u +\w'MSG_DONTROUTE\ \ \ 'u +\w'0x\0\0\0\ \ 'u |
a9e7c426 KM |
95 | #define MSG_OOB 0x1 /* process out-of-band data */ |
96 | #define MSG_PEEK 0x2 /* peek at incoming message */ | |
03e70dcd KM |
97 | .RE |
98 | .fi | |
99 | .PP | |
100 | The | |
101 | .I recvmsg | |
102 | call uses a | |
103 | .I msghdr | |
104 | structure to minimize the number of directly supplied parameters. | |
105 | This structure has the following form, as defined in | |
106 | .IR <sys/socket.h> : | |
107 | .PP | |
108 | .nf | |
109 | .RS | |
110 | .DT | |
111 | struct msghdr { | |
112 | caddr_t msg_name; /* optional address */ | |
113 | int msg_namelen; /* size of address */ | |
a9e7c426 | 114 | struct iovec *msg_iov; /* scatter/gather array */ |
03e70dcd KM |
115 | int msg_iovlen; /* # elements in msg_iov */ |
116 | caddr_t msg_accrights; /* access rights sent/received */ | |
117 | int msg_accrightslen; | |
118 | }; | |
119 | .RE | |
120 | .fi | |
121 | .PP | |
122 | Here | |
123 | .I msg_name | |
124 | and | |
125 | .I msg_namelen | |
126 | specify the destination address if the socket is unconnected; | |
127 | .I msg_name | |
128 | may be given as a null pointer if no names are desired or required. | |
129 | The | |
130 | .I msg_iov | |
131 | and | |
132 | .I msg_iovlen | |
133 | describe the scatter gather locations, as described in | |
134 | .IR read (2). | |
def9d0f9 | 135 | A buffer to receive any access rights sent along with the message is specified |
03e70dcd KM |
136 | in |
137 | .IR msg_accrights , | |
138 | which has length | |
139 | .IR msg_accrightslen . | |
def9d0f9 MK |
140 | Access rights are currently limited to file descriptors, |
141 | which each occupy the size of an | |
142 | .BR int . | |
758e5b44 KB |
143 | If access rights are not being transferred, the |
144 | .I msg_accrights | |
145 | field should be set to NULL. | |
03e70dcd KM |
146 | .SH "RETURN VALUE |
147 | These calls return the number of bytes received, or \-1 | |
148 | if an error occurred. | |
149 | .SH ERRORS | |
150 | The calls fail if: | |
151 | .TP 20 | |
152 | [EBADF] | |
153 | The argument \fIs\fP is an invalid descriptor. | |
154 | .TP 20 | |
155 | [ENOTSOCK] | |
156 | The argument \fIs\fP is not a socket. | |
157 | .TP 20 | |
158 | [EWOULDBLOCK] | |
159 | The socket is marked non-blocking and the receive operation | |
160 | would block. | |
161 | .TP 20 | |
162 | [EINTR] | |
163 | The receive was interrupted by delivery of a signal before | |
164 | any data was available for the receive. | |
165 | .TP 20 | |
166 | [EFAULT] | |
167 | The data was specified to be received into a non-existent | |
168 | or protected part of the process address space. | |
169 | .SH SEE ALSO | |
def9d0f9 | 170 | fcntl(2), read(2), send(2), select(2), getsockopt(2), socket(2) |