| blob | d6fed98180d4e6d25d9a6479cb5e2e3fa985c329 |
1 .\" $OpenBSD: connect.2,v 1.31 2016/08/20 20:22:28 millert Exp $
2 .\" $NetBSD: connect.2,v 1.8 1995/10/12 15:40:48 jtc Exp $
3 .\"
4 .\" Copyright (c) 1983, 1993
5 .\" The Regents of the University of California. All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. Neither the name of the University nor the names of its contributors
16 .\" may be used to endorse or promote products derived from this software
17 .\" without specific prior written permission.
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 .\" SUCH DAMAGE.
30 .\"
31 .\" @(#)connect.2 8.1 (Berkeley) 6/4/93
32 .\"
33 .Dd October 24, 2016
34 .Dt CONNECT 2
35 .Os
36 .Sh NAME
37 .Nm connect
38 .Nd initiate a connection on a socket
39 .Sh SYNOPSIS
40 .In sys/socket.h
41 .Ft int
42 .Fn connect "int s" "const struct sockaddr *name" "socklen_t namelen"
43 .Sh DESCRIPTION
44 The parameter
45 .Fa s
46 is a socket.
47 If it is of type
48 .Dv SOCK_DGRAM ,
49 this call specifies the peer with which the socket is to be associated;
50 this address is that to which datagrams are to be sent,
51 and the only address from which datagrams are to be received.
52 If the socket is of type
53 .Dv SOCK_STREAM ,
54 this call attempts to make a connection to
55 another socket.
56 The other socket is specified by
57 .Fa name ,
58 which is an address in the communications space of the socket.
59 .Fa namelen
60 indicates the amount of space pointed to by
61 .Fa name ,
62 in bytes; the
63 .Fa sa_len
64 member of
65 .Fa name
66 is ignored.
67 Each communications space interprets the
68 .Fa name
69 parameter in its own way.
70 Generally, stream sockets may use
71 .Fn connect
72 only once; datagram sockets may use
73 .Fn connect
74 multiple times to change their association.
75 Datagram sockets may dissolve the association
76 by connecting to an invalid address, such as a null address.
77 .Pp
78 If the socket is in non-blocking mode and the connection cannot be
79 completed immediately, or if it is interrupted by a signal,
80 .Fn connect
81 will return an error and the connection attempt will proceed
82 asynchronously.
83 Subsequent calls to
84 .Fn connect
85 will fail with errno set to
86 .Er EALREADY .
87 It is possible to use
88 .Xr select 2
89 or
90 .Xr poll 2
91 to determine when the connect operation has completed by checking the
92 socket for writability.
93 The success or failure of the connection attempt may be determined by using
94 .Xr getsockopt 2
95 to check the socket error status with the
96 .Dv SO_ERROR
97 option at the
98 .Dv SOL_SOCKET
99 level.
100 If the connection was successful, the error value will be zero.
101 Otherwise, it will be one of the error values listed below.
102 .Sh RETURN VALUES
103 If the connection or binding succeeds, 0 is returned.
104 Otherwise a \-1 is returned, and a more specific error
105 code is stored in
106 .Va errno .
107 .Sh EXAMPLES
108 The following code connects to the host described by
109 .Fa name
110 and handles the case where
111 .Fn connect
112 is interrupted by a signal.
113 .Bd -literal -offset indent
114 #include <sys/socket.h>
115 #include <poll.h>
116 #include <errno.h>
117 #include <err.h>
119 int
120 connect_wait(int s)
121 {
122 struct pollfd pfd[1];
123 int error = 0;
124 socklen_t len = sizeof(error);
126 pfd[0].fd = s;
127 pfd[0].events = POLLOUT;
129 if (poll(pfd, 1, -1) == -1)
130 return -1;
131 if (getsockopt(s, SOL_SOCKET, SO_ERROR, &error, &len) < 0)
132 return -1;
133 if (error != 0) {
134 errno = error;
135 return -1;
136 }
137 return 0;
138 }
140 \&...
142 int retcode;
144 \&...
146 for (retcode = connect(s, name, namelen);
147 retcode != 0 && errno == EINTR;
148 retcode = connect_wait(s))
149 continue;
150 if (retcode == -1)
151 err(1, "connect");
152 .Ed
153 .Sh ERRORS
154 The
155 .Fn connect
156 call fails if:
157 .Bl -tag -width Er
158 .It Bq Er EBADF
159 .Fa s
160 is not a valid descriptor.
161 .It Bq Er ENOTSOCK
162 .Fa s
163 is not a socket.
164 .It Bq Er EADDRNOTAVAIL
165 The specified address is not available on this machine.
166 .It Bq Er EAFNOSUPPORT
167 Addresses in the specified address family cannot be used with this socket.
168 .It Bq Er EISCONN
169 The socket is already connected.
170 .It Bq Er ETIMEDOUT
171 Connection establishment timed out without establishing a connection.
172 .It Bq Er EINVAL
173 A TCP connection with a local broadcast, the all-ones or a
174 multicast address as the peer was attempted, or
175 .Fa namelen
176 is not a valid length for the address family.
177 .It Bq Er ECONNREFUSED
178 The attempt to connect was forcefully rejected.
179 .It Bq Er EHOSTUNREACH
180 The destination address specified an unreachable host.
181 .It Bq Er EINTR
182 The connection attempt was interrupted by a signal.
183 The attempt will continue asynchronously as if the socket was non-blocking.
184 .It Bq Er ENETUNREACH
185 The network isn't reachable from this host.
186 .It Bq Er EADDRINUSE
187 The address is already in use.
188 .It Bq Er EFAULT
189 The
190 .Fa name
191 parameter specifies an area outside
192 the process address space.
193 .It Bq Er EINPROGRESS
194 The socket is non-blocking and the connection cannot
195 be completed immediately.
196 .It Bq Er EALREADY
197 Either the socket is non-blocking or a previous call to
198 .Fn connect
199 was interrupted by a signal, and the connection attempt has not yet
200 been completed.
201 .El
202 .Pp
203 The following errors are specific to connecting names in the
204 .Ux Ns -domain .
205 These errors may not apply in future versions of the
206 .Ux
207 IPC domain.
208 .Bl -tag -width Er
209 .It Bq Er ENOTDIR
210 A component of the path prefix is not a directory.
211 .It Bq Er ENAMETOOLONG
212 A component of a pathname exceeded
213 .Dv NAME_MAX
214 characters, or an entire pathname (including the terminating NUL)
215 exceeded
216 .Dv PATH_MAX
217 bytes.
218 .It Bq Er ENOENT
219 The named socket does not exist.
220 .It Bq Er EACCES
221 Search permission is denied for a component of the path prefix.
222 .It Bq Er EACCES
223 Write access to the named socket is denied.
224 .It Bq Er ELOOP
225 Too many symbolic links were encountered in translating the pathname.
226 .It Bq Er EPROTOTYPE
227 The file described by
228 .Fa name
229 is of a different type than
230 .Fa s .
231 E.g.,
232 .Fa s
233 may be of type
234 .Dv SOCK_STREAM
235 whereas
236 .Fa name
237 may refer to a socket of type
238 .Dv SOCK_DGRAM .
239 .It Bq Er EIO
240 An I/O error occurred.
241 .El
242 .Sh SEE ALSO
243 .Xr accept 2 ,
244 .Xr getsockname 2 ,
245 .Xr getsockopt 2 ,
246 .Xr poll 2 ,
247 .Xr select 2 ,
248 .Xr socket 2
249 .Sh STANDARDS
250 The
251 .Fn connect
252 function conforms to
253 .St -p1003.1-2008 .
254 .Sh HISTORY
255 The
256 .Fn connect
257 system call first appeared in
258 .Bx 4.1c .