]>
Commit | Line | Data |
---|---|---|
77117f4f MK |
1 | .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) |
2 | .\" Portions extracted from /usr/include/sys/socket.h, which does not have | |
3 | .\" any authorship information in it. It is probably available under the GPL. | |
4 | .\" | |
5fbde956 | 5 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
77117f4f MK |
6 | .\" |
7 | .\" | |
8 | .\" Other portions are from the 6.9 (Berkeley) 3/10/91 man page: | |
9 | .\" | |
10 | .\" Copyright (c) 1983 The Regents of the University of California. | |
11 | .\" All rights reserved. | |
12 | .\" | |
47009d5e | 13 | .\" SPDX-License-Identifier: BSD-4-Clause-UC |
77117f4f MK |
14 | .\" |
15 | .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> | |
16 | .\" Modified 1998, 1999 by Andi Kleen | |
17 | .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> | |
18 | .\" | |
4c1c5274 | 19 | .TH connect 2 (date) "Linux man-pages (unreleased)" |
77117f4f MK |
20 | .SH NAME |
21 | connect \- initiate a connection on a socket | |
f2f22258 AC |
22 | .SH LIBRARY |
23 | Standard C library | |
8fc3b2cf | 24 | .RI ( libc ", " \-lc ) |
77117f4f MK |
25 | .SH SYNOPSIS |
26 | .nf | |
77117f4f | 27 | .B #include <sys/socket.h> |
c6d039a3 | 28 | .P |
a2b8b6d6 | 29 | .BI "int connect(int " sockfd ", const struct sockaddr *" addr , |
77117f4f MK |
30 | .BI " socklen_t " addrlen ); |
31 | .fi | |
32 | .SH DESCRIPTION | |
33 | The | |
34 | .BR connect () | |
35 | system call connects the socket referred to by the file descriptor | |
36 | .I sockfd | |
37 | to the address specified by | |
a2b8b6d6 | 38 | .IR addr . |
77117f4f MK |
39 | The |
40 | .I addrlen | |
41 | argument specifies the size of | |
a2b8b6d6 | 42 | .IR addr . |
77117f4f | 43 | The format of the address in |
a2b8b6d6 | 44 | .I addr |
77117f4f MK |
45 | is determined by the address space of the socket |
46 | .IR sockfd ; | |
47 | see | |
48 | .BR socket (2) | |
49 | for further details. | |
c6d039a3 | 50 | .P |
77117f4f MK |
51 | If the socket |
52 | .I sockfd | |
53 | is of type | |
45d522a8 | 54 | .BR SOCK_DGRAM , |
77117f4f | 55 | then |
a2b8b6d6 | 56 | .I addr |
77117f4f MK |
57 | is the address to which datagrams are sent by default, and the only |
58 | address from which datagrams are received. | |
59 | If the socket is of type | |
60 | .B SOCK_STREAM | |
61 | or | |
62 | .BR SOCK_SEQPACKET , | |
63 | this call attempts to make a connection to the socket that is bound | |
64 | to the address specified by | |
a2b8b6d6 | 65 | .IR addr . |
c6d039a3 | 66 | .P |
f4ba6a21 MK |
67 | Some protocol sockets (e.g., UNIX domain stream sockets) |
68 | may successfully | |
77117f4f | 69 | .BR connect () |
f4ba6a21 | 70 | only once. |
c6d039a3 | 71 | .P |
f4ba6a21 MK |
72 | Some protocol sockets |
73 | (e.g., datagram sockets in the UNIX and Internet domains) | |
74 | may use | |
77117f4f MK |
75 | .BR connect () |
76 | multiple times to change their association. | |
c6d039a3 | 77 | .P |
f4ba6a21 MK |
78 | Some protocol sockets |
79 | (e.g., TCP sockets as well as datagram sockets in the UNIX and | |
80 | Internet domains) | |
81 | may dissolve the association by connecting to an address with the | |
77117f4f MK |
82 | .I sa_family |
83 | member of | |
84 | .I sockaddr | |
85 | set to | |
575bac0f | 86 | .BR AF_UNSPEC ; |
f4ba6a21 MK |
87 | thereafter, the socket can be connected to another address. |
88 | .RB ( AF_UNSPEC | |
b324e17d | 89 | is supported since Linux 2.2.) |
47297adb | 90 | .SH RETURN VALUE |
77117f4f MK |
91 | If the connection or binding succeeds, zero is returned. |
92 | On error, \-1 is returned, and | |
93 | .I errno | |
f6a4078b | 94 | is set to indicate the error. |
77117f4f MK |
95 | .SH ERRORS |
96 | The following are general socket errors only. | |
97 | There may be other domain-specific error codes. | |
98 | .TP | |
99 | .B EACCES | |
008f1ecc | 100 | For UNIX domain sockets, which are identified by pathname: |
77117f4f MK |
101 | Write permission is denied on the socket file, |
102 | or search permission is denied for one of the directories | |
103 | in the path prefix. | |
104 | (See also | |
105 | .BR path_resolution (7).) | |
106 | .TP | |
6fdb1c03 AC |
107 | .B EACCES |
108 | .TQ | |
109 | .B EPERM | |
77117f4f MK |
110 | The user tried to connect to a broadcast address without having the socket |
111 | broadcast flag enabled or the connection request failed because of a local | |
112 | firewall rule. | |
4e17653f | 113 | .TP |
375c65a9 | 114 | .B EACCES |
4e17653f | 115 | It can also be returned if an SELinux policy denied a connection (for |
375c65a9 SP |
116 | example, if there is a policy saying that an HTTP proxy can only |
117 | connect to ports associated with HTTP servers, and the proxy tries to | |
118 | connect to a different port). | |
77117f4f MK |
119 | .TP |
120 | .B EADDRINUSE | |
121 | Local address is already in use. | |
122 | .TP | |
ac7477eb MK |
123 | .B EADDRNOTAVAIL |
124 | (Internet domain sockets) | |
125 | The socket referred to by | |
126 | .I sockfd | |
127 | had not previously been bound to an address and, | |
128 | upon attempting to bind it to an ephemeral port, | |
129 | it was determined that all port numbers in the ephemeral port range | |
130 | are currently in use. | |
131 | See the discussion of | |
132 | .I /proc/sys/net/ipv4/ip_local_port_range | |
133 | in | |
134 | .BR ip (7). | |
135 | .TP | |
77117f4f MK |
136 | .B EAFNOSUPPORT |
137 | The passed address didn't have the correct address family in its | |
138 | .I sa_family | |
139 | field. | |
140 | .TP | |
141 | .B EAGAIN | |
14662577 | 142 | For nonblocking UNIX domain sockets, the socket is nonblocking, and the |
55dc41dc MK |
143 | connection cannot be completed immediately. |
144 | For other socket families, there are insufficient entries in the routing cache. | |
77117f4f MK |
145 | .TP |
146 | .B EALREADY | |
ff40dbb3 | 147 | The socket is nonblocking and a previous connection attempt has not yet |
77117f4f MK |
148 | been completed. |
149 | .TP | |
150 | .B EBADF | |
d60d564d MK |
151 | .I sockfd |
152 | is not a valid open file descriptor. | |
77117f4f MK |
153 | .TP |
154 | .B ECONNREFUSED | |
96a35a83 MK |
155 | A |
156 | .BR connect () | |
157 | on a stream socket found no one listening on the remote address. | |
77117f4f MK |
158 | .TP |
159 | .B EFAULT | |
160 | The socket structure address is outside the user's address space. | |
161 | .TP | |
162 | .B EINPROGRESS | |
55dc41dc | 163 | The socket is nonblocking and the connection cannot be completed immediately. |
85bb10df | 164 | (UNIX domain sockets failed with |
1ae6b2c7 | 165 | .B EAGAIN |
14662577 | 166 | instead.) |
77117f4f MK |
167 | It is possible to |
168 | .BR select (2) | |
169 | or | |
170 | .BR poll (2) | |
171 | for completion by selecting the socket for writing. | |
172 | After | |
173 | .BR select (2) | |
174 | indicates writability, use | |
175 | .BR getsockopt (2) | |
176 | to read the | |
177 | .B SO_ERROR | |
178 | option at level | |
179 | .B SOL_SOCKET | |
180 | to determine whether | |
181 | .BR connect () | |
182 | completed successfully | |
183 | .RB ( SO_ERROR | |
184 | is zero) or unsuccessfully | |
185 | .RB ( SO_ERROR | |
186 | is one of the usual error codes listed here, | |
187 | explaining the reason for the failure). | |
188 | .TP | |
189 | .B EINTR | |
190 | The system call was interrupted by a signal that was caught; see | |
191 | .BR signal (7). | |
192 | .\" For TCP, the connection will complete asynchronously. | |
193 | .\" See http://lkml.org/lkml/2005/7/12/254 | |
194 | .TP | |
195 | .B EISCONN | |
196 | The socket is already connected. | |
197 | .TP | |
198 | .B ENETUNREACH | |
199 | Network is unreachable. | |
200 | .TP | |
201 | .B ENOTSOCK | |
deedfd97 MK |
202 | The file descriptor |
203 | .I sockfd | |
204 | does not refer to a socket. | |
77117f4f | 205 | .TP |
65558bed MK |
206 | .B EPROTOTYPE |
207 | The socket type does not support the requested communications protocol. | |
208 | This error can occur, for example, | |
209 | on an attempt to connect a UNIX domain datagram socket to a stream socket. | |
210 | .TP | |
77117f4f MK |
211 | .B ETIMEDOUT |
212 | Timeout while attempting connection. | |
213 | The server may be too | |
214 | busy to accept new connections. | |
215 | Note that for IP sockets the timeout may | |
216 | be very long when syncookies are enabled on the server. | |
3113c7f3 | 217 | .SH STANDARDS |
4131356c AC |
218 | POSIX.1-2008. |
219 | .SH HISTORY | |
220 | POSIX.1-2001, SVr4, 4.4BSD, | |
d5bc35a7 MK |
221 | .RB (connect () |
222 | first appeared in 4.2BSD). | |
77117f4f MK |
223 | .\" SVr4 documents the additional |
224 | .\" general error codes | |
225 | .\" .BR EADDRNOTAVAIL , | |
226 | .\" .BR EINVAL , | |
227 | .\" .BR EAFNOSUPPORT , | |
228 | .\" .BR EALREADY , | |
229 | .\" .BR EINTR , | |
230 | .\" .BR EPROTOTYPE , | |
231 | .\" and | |
232 | .\" .BR ENOSR . | |
233 | .\" It also | |
234 | .\" documents many additional error conditions not described here. | |
235 | .SH NOTES | |
977e3384 | 236 | If |
536f641b | 237 | .BR connect () |
977e3384 MH |
238 | fails, consider the state of the socket as unspecified. |
239 | Portable applications should close the socket and create a new one for | |
240 | reconnecting. | |
a14af333 | 241 | .SH EXAMPLES |
77117f4f MK |
242 | An example of the use of |
243 | .BR connect () | |
244 | is shown in | |
245 | .BR getaddrinfo (3). | |
47297adb | 246 | .SH SEE ALSO |
77117f4f MK |
247 | .BR accept (2), |
248 | .BR bind (2), | |
249 | .BR getsockname (2), | |
250 | .BR listen (2), | |
251 | .BR socket (2), | |
375c65a9 SP |
252 | .BR path_resolution (7), |
253 | .BR selinux (8) |