Debian Codegraph @

upstream/debian-trixie/man2/connect.2

raw
1 .\" Copyright 1993 Rickard E. Faith ([email protected])
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 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
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 .\"
13 .\" SPDX-License-Identifier: BSD-4-Clause-UC
14 .\"
15 .\" Modified 1997-01-31 by Eric S. Raymond <[email protected]>
16 .\" Modified 1998, 1999 by Andi Kleen
17 .\" Modified 2004-06-23 by Michael Kerrisk <[email protected]>
18 .\"
19 .TH connect 2 2024-05-02 "Linux man-pages 6.9.1"
20 .SH NAME
21 connect \- initiate a connection on a socket
22 .SH LIBRARY
23 Standard C library
24 .RI ( libc ", " \-lc )
25 .SH SYNOPSIS
26 .nf
27 .B #include <sys/socket.h>
28 .P
29 .BI "int connect(int " sockfd ", const struct sockaddr *" addr ,
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
38 .IR addr .
39 The
40 .I addrlen
41 argument specifies the size of
42 .IR addr .
43 The format of the address in
44 .I addr
45 is determined by the address space of the socket
46 .IR sockfd ;
47 see
48 .BR socket (2)
49 for further details.
50 .P
51 If the socket
52 .I sockfd
53 is of type
54 .BR SOCK_DGRAM ,
55 then
56 .I addr
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
65 .IR addr .
66 .P
67 Some protocol sockets (e.g., UNIX domain stream sockets)
68 may successfully
69 .BR connect ()
70 only once.
71 .P
72 Some protocol sockets
73 (e.g., datagram sockets in the UNIX and Internet domains)
74 may use
75 .BR connect ()
76 multiple times to change their association.
77 .P
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
82 .I sa_family
83 member of
84 .I sockaddr
85 set to
86 .BR AF_UNSPEC ;
87 thereafter, the socket can be connected to another address.
88 .RB ( AF_UNSPEC
89 is supported since Linux 2.2.)
90 .SH RETURN VALUE
91 If the connection or binding succeeds, zero is returned.
92 On error, \-1 is returned, and
93 .I errno
94 is set to indicate the error.
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
100 For UNIX domain sockets, which are identified by pathname:
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 .B EACCES
108 .TQ
109 .B EPERM
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.
113 .TP
114 .B EACCES
115 It can also be returned if an SELinux policy denied a connection (for
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).
119 .TP
120 .B EADDRINUSE
121 Local address is already in use.
122 .TP
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
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
142 For nonblocking UNIX domain sockets, the socket is nonblocking, and the
143 connection cannot be completed immediately.
144 For other socket families, there are insufficient entries in the routing cache.
145 .TP
146 .B EALREADY
147 The socket is nonblocking and a previous connection attempt has not yet
148 been completed.
149 .TP
150 .B EBADF
151 .I sockfd
152 is not a valid open file descriptor.
153 .TP
154 .B ECONNREFUSED
155 A
156 .BR connect ()
157 on a stream socket found no one listening on the remote address.
158 .TP
159 .B EFAULT
160 The socket structure address is outside the user's address space.
161 .TP
162 .B EINPROGRESS
163 The socket is nonblocking and the connection cannot be completed immediately.
164 (UNIX domain sockets failed with
165 .B EAGAIN
166 instead.)
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
202 The file descriptor
203 .I sockfd
204 does not refer to a socket.
205 .TP
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
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.
217 .SH STANDARDS
218 POSIX.1-2008.
219 .SH HISTORY
220 POSIX.1-2001, SVr4, 4.4BSD,
221 .RB ( connect ()
222 first appeared in 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)