Debian Codegraph @

upstream/debian-unstable/man2/connect.2

raw
1 .\" Copyright 1993, Rickard E. Faith <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\"
7 .\" Other portions are from the 6.9 (Berkeley) 3/10/91 man page:
8 .\"
9 .\" Copyright 1983, The Regents of the University of California.
10 .\"
11 .\" SPDX-License-Identifier: BSD-4-Clause-UC
12 .\"
13 .TH connect 2 2026-02-08 "Linux man-pages 6.18"
14 .SH NAME
15 connect \- initiate a connection on a socket
16 .SH LIBRARY
17 Standard C library
18 .RI ( libc ,\~ \-lc )
19 .SH SYNOPSIS
20 .nf
21 .B #include <sys/socket.h>
22 .P
23 .BI "int connect(int " sockfd ", const struct sockaddr *" addr ,
24 .BI " socklen_t " addrlen );
25 .fi
26 .SH DESCRIPTION
27 The
28 .BR connect ()
29 system call connects the socket referred to by the file descriptor
30 .I sockfd
31 to the address specified by
32 .IR addr .
33 The
34 .I addrlen
35 argument specifies the size of
36 .IR addr .
37 The format of the address in
38 .I addr
39 is determined by the address space of the socket
40 .IR sockfd ;
41 see
42 .BR socket (2)
43 for further details.
44 .P
45 If the socket
46 .I sockfd
47 is of type
48 .BR SOCK_DGRAM ,
49 then
50 .I addr
51 is the address to which datagrams are sent by default, and the only
52 address from which datagrams are received.
53 If the socket is of type
54 .B SOCK_STREAM
55 or
56 .BR SOCK_SEQPACKET ,
57 this call attempts to make a connection to the socket that is bound
58 to the address specified by
59 .IR addr .
60 .P
61 Some protocol sockets (e.g., UNIX domain stream sockets)
62 may successfully
63 .BR connect ()
64 only once.
65 .P
66 Some protocol sockets
67 (e.g., datagram sockets in the UNIX and Internet domains)
68 may use
69 .BR connect ()
70 multiple times to change their association.
71 .P
72 Some protocol sockets
73 (e.g., TCP sockets as well as datagram sockets in the UNIX and
74 Internet domains)
75 may dissolve the association by connecting to an address with the
76 .I sa_family
77 member of
78 .I sockaddr
79 set to
80 .BR AF_UNSPEC ;
81 thereafter, the socket can be connected to another address.
82 .RB ( AF_UNSPEC
83 is supported since Linux 2.2.)
84 .SH RETURN VALUE
85 If the connection or binding succeeds, zero is returned.
86 On error, \-1 is returned, and
87 .I errno
88 is set to indicate the error.
89 .SH ERRORS
90 The following are general socket errors only.
91 There may be other domain-specific error codes.
92 .TP
93 .B EACCES
94 For UNIX domain sockets, which are identified by pathname:
95 Write permission is denied on the socket file,
96 or search permission is denied for one of the directories
97 in the path prefix.
98 (See also
99 .BR path_resolution (7).)
100 .TP
101 .B EACCES
102 .TQ
103 .B EPERM
104 The user tried to connect to a broadcast address without having the socket
105 broadcast flag enabled or the connection request failed because of a local
106 firewall rule.
107 .TP
108 .B EACCES
109 It can also be returned if an SELinux policy denied a connection (for
110 example, if there is a policy saying that an HTTP proxy can only
111 connect to ports associated with HTTP servers, and the proxy tries to
112 connect to a different port).
113 .TP
114 .B EADDRINUSE
115 Local address is already in use.
116 .TP
117 .B EADDRNOTAVAIL
118 (Internet domain sockets)
119 The socket referred to by
120 .I sockfd
121 had not previously been bound to an address and,
122 upon attempting to bind it to an ephemeral port,
123 it was determined that all port numbers in the ephemeral port range
124 are currently in use.
125 See the discussion of
126 .I /proc/sys/net/ipv4/ip_local_port_range
127 in
128 .BR ip (7).
129 .TP
130 .B EAFNOSUPPORT
131 The passed address didn't have the correct address family in its
132 .I sa_family
133 field.
134 .TP
135 .B EAGAIN
136 For nonblocking UNIX domain sockets, the socket is nonblocking, and the
137 connection cannot be completed immediately.
138 For other socket families, there are insufficient entries in the routing cache.
139 .TP
140 .B EALREADY
141 The socket is nonblocking and a previous connection attempt has not yet
142 been completed.
143 .TP
144 .B EBADF
145 .I sockfd
146 is not a valid open file descriptor.
147 .TP
148 .B ECONNREFUSED
149 A
150 .BR connect ()
151 on a stream socket found no one listening on the remote address.
152 .TP
153 .B EFAULT
154 The socket structure address is outside the user's address space.
155 .TP
156 .B EINPROGRESS
157 The socket is nonblocking and the connection cannot be completed immediately.
158 (UNIX domain sockets failed with
159 .B EAGAIN
160 instead.)
161 It is possible to
162 .BR select (2)
163 or
164 .BR poll (2)
165 for completion by selecting the socket for writing.
166 After
167 .BR select (2)
168 indicates writability, use
169 .BR getsockopt (2)
170 to read the
171 .B SO_ERROR
172 option at level
173 .B SOL_SOCKET
174 to determine whether
175 .BR connect ()
176 completed successfully
177 .RB ( SO_ERROR
178 is zero) or unsuccessfully
179 .RB ( SO_ERROR
180 is one of the usual error codes listed here,
181 explaining the reason for the failure).
182 .TP
183 .B EINTR
184 The system call was interrupted by a signal that was caught;
185 see
186 .BR signal (7).
187 .\" For TCP, the connection will complete asynchronously.
188 .\" See http://lkml.org/lkml/2005/7/12/254
189 .TP
190 .B EISCONN
191 The socket is already connected.
192 .TP
193 .B ENETUNREACH
194 Network is unreachable.
195 .TP
196 .B ENOTSOCK
197 The file descriptor
198 .I sockfd
199 does not refer to a socket.
200 .TP
201 .B EPROTOTYPE
202 The socket type does not support the requested communications protocol.
203 This error can occur, for example,
204 on an attempt to connect a UNIX domain datagram socket to a stream socket.
205 .TP
206 .B ETIMEDOUT
207 Timeout while attempting connection.
208 The server may be too
209 busy to accept new connections.
210 Note that for IP sockets the timeout may
211 be very long when syncookies are enabled on the server.
212 .SH VERSIONS
213 Portable programs must ensure that
214 .I addr.sun_path
215 is a null-terminated string
216 for
217 .B AF_UNIX
218 sockets.
219 .SH STANDARDS
220 POSIX.1-2024.
221 .SH HISTORY
222 POSIX.1-2001, SVr4, 4.2BSD.
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
236 If
237 .BR connect ()
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.
241 .SH EXAMPLES
242 An example of the use of
243 .BR connect ()
244 is shown in
245 .BR getaddrinfo (3).
246 .SH SEE ALSO
247 .BR accept (2),
248 .BR bind (2),
249 .BR getsockname (2),
250 .BR listen (2),
251 .BR socket (2),
252 .BR path_resolution (7),
253 .BR selinux (8)