]>
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 | .\" | |
1d767b55 | 19 | .TH CONNECT 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
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> |
68e4db0a | 28 | .PP |
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. | |
efeece04 | 50 | .PP |
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 . |
77117f4f | 66 | .PP |
f4ba6a21 MK |
67 | Some protocol sockets (e.g., UNIX domain stream sockets) |
68 | may successfully | |
77117f4f | 69 | .BR connect () |
f4ba6a21 MK |
70 | only once. |
71 | .PP | |
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. | |
f4ba6a21 MK |
77 | .PP |
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 | |
89 | is supported on Linux since kernel 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 | |
107 | .BR EACCES ", " EPERM | |
108 | The user tried to connect to a broadcast address without having the socket | |
109 | broadcast flag enabled or the connection request failed because of a local | |
110 | firewall rule. | |
492a8b72 | 111 | .IP |
375c65a9 | 112 | .B EACCES |
492a8b72 | 113 | can also be returned if an SELinux policy denied a connection (for |
375c65a9 SP |
114 | example, if there is a policy saying that an HTTP proxy can only |
115 | connect to ports associated with HTTP servers, and the proxy tries to | |
116 | connect to a different port). | |
492a8b72 | 117 | dd |
77117f4f MK |
118 | .TP |
119 | .B EADDRINUSE | |
120 | Local address is already in use. | |
121 | .TP | |
ac7477eb MK |
122 | .B EADDRNOTAVAIL |
123 | (Internet domain sockets) | |
124 | The socket referred to by | |
125 | .I sockfd | |
126 | had not previously been bound to an address and, | |
127 | upon attempting to bind it to an ephemeral port, | |
128 | it was determined that all port numbers in the ephemeral port range | |
129 | are currently in use. | |
130 | See the discussion of | |
131 | .I /proc/sys/net/ipv4/ip_local_port_range | |
132 | in | |
133 | .BR ip (7). | |
134 | .TP | |
77117f4f MK |
135 | .B EAFNOSUPPORT |
136 | The passed address didn't have the correct address family in its | |
137 | .I sa_family | |
138 | field. | |
139 | .TP | |
140 | .B EAGAIN | |
14662577 | 141 | For nonblocking UNIX domain sockets, the socket is nonblocking, and the |
55dc41dc MK |
142 | connection cannot be completed immediately. |
143 | For other socket families, there are insufficient entries in the routing cache. | |
77117f4f MK |
144 | .TP |
145 | .B EALREADY | |
ff40dbb3 | 146 | The socket is nonblocking and a previous connection attempt has not yet |
77117f4f MK |
147 | been completed. |
148 | .TP | |
149 | .B EBADF | |
d60d564d MK |
150 | .I sockfd |
151 | is not a valid open file descriptor. | |
77117f4f MK |
152 | .TP |
153 | .B ECONNREFUSED | |
96a35a83 MK |
154 | A |
155 | .BR connect () | |
156 | on a stream socket found no one listening on the remote address. | |
77117f4f MK |
157 | .TP |
158 | .B EFAULT | |
159 | The socket structure address is outside the user's address space. | |
160 | .TP | |
161 | .B EINPROGRESS | |
55dc41dc | 162 | The socket is nonblocking and the connection cannot be completed immediately. |
85bb10df | 163 | (UNIX domain sockets failed with |
1ae6b2c7 | 164 | .B EAGAIN |
14662577 | 165 | instead.) |
77117f4f MK |
166 | It is possible to |
167 | .BR select (2) | |
168 | or | |
169 | .BR poll (2) | |
170 | for completion by selecting the socket for writing. | |
171 | After | |
172 | .BR select (2) | |
173 | indicates writability, use | |
174 | .BR getsockopt (2) | |
175 | to read the | |
176 | .B SO_ERROR | |
177 | option at level | |
178 | .B SOL_SOCKET | |
179 | to determine whether | |
180 | .BR connect () | |
181 | completed successfully | |
182 | .RB ( SO_ERROR | |
183 | is zero) or unsuccessfully | |
184 | .RB ( SO_ERROR | |
185 | is one of the usual error codes listed here, | |
186 | explaining the reason for the failure). | |
187 | .TP | |
188 | .B EINTR | |
189 | The system call was interrupted by a signal that was caught; see | |
190 | .BR signal (7). | |
191 | .\" For TCP, the connection will complete asynchronously. | |
192 | .\" See http://lkml.org/lkml/2005/7/12/254 | |
193 | .TP | |
194 | .B EISCONN | |
195 | The socket is already connected. | |
196 | .TP | |
197 | .B ENETUNREACH | |
198 | Network is unreachable. | |
199 | .TP | |
200 | .B ENOTSOCK | |
deedfd97 MK |
201 | The file descriptor |
202 | .I sockfd | |
203 | does not refer to a socket. | |
77117f4f | 204 | .TP |
65558bed MK |
205 | .B EPROTOTYPE |
206 | The socket type does not support the requested communications protocol. | |
207 | This error can occur, for example, | |
208 | on an attempt to connect a UNIX domain datagram socket to a stream socket. | |
209 | .TP | |
77117f4f MK |
210 | .B ETIMEDOUT |
211 | Timeout while attempting connection. | |
212 | The server may be too | |
213 | busy to accept new connections. | |
214 | Note that for IP sockets the timeout may | |
215 | be very long when syncookies are enabled on the server. | |
47297adb | 216 | .SH CONFORMING TO |
d5bc35a7 MK |
217 | POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD, |
218 | .RB (connect () | |
219 | first appeared in 4.2BSD). | |
77117f4f MK |
220 | .\" SVr4 documents the additional |
221 | .\" general error codes | |
222 | .\" .BR EADDRNOTAVAIL , | |
223 | .\" .BR EINVAL , | |
224 | .\" .BR EAFNOSUPPORT , | |
225 | .\" .BR EALREADY , | |
226 | .\" .BR EINTR , | |
227 | .\" .BR EPROTOTYPE , | |
228 | .\" and | |
229 | .\" .BR ENOSR . | |
230 | .\" It also | |
231 | .\" documents many additional error conditions not described here. | |
232 | .SH NOTES | |
ec5df7af MK |
233 | For background on the |
234 | .I socklen_t | |
235 | type, see | |
77117f4f | 236 | .BR accept (2). |
efeece04 | 237 | .PP |
977e3384 | 238 | If |
536f641b | 239 | .BR connect () |
977e3384 MH |
240 | fails, consider the state of the socket as unspecified. |
241 | Portable applications should close the socket and create a new one for | |
242 | reconnecting. | |
a14af333 | 243 | .SH EXAMPLES |
77117f4f MK |
244 | An example of the use of |
245 | .BR connect () | |
246 | is shown in | |
247 | .BR getaddrinfo (3). | |
47297adb | 248 | .SH SEE ALSO |
77117f4f MK |
249 | .BR accept (2), |
250 | .BR bind (2), | |
251 | .BR getsockname (2), | |
252 | .BR listen (2), | |
253 | .BR socket (2), | |
375c65a9 SP |
254 | .BR path_resolution (7), |
255 | .BR selinux (8) |