1 CONNECT(3SOCKET) Sockets Library Functions CONNECT(3SOCKET)
2
3
4
5 NAME
6 connect - initiate a connection on a socket
7
8 SYNOPSIS
9 cc [ flag ... ] file ... -lsocket -lnsl [ library ... ]
10 #include <sys/types.h>
11 #include <sys/socket.h>
12
13
14
15 int connect(int s, const struct sockaddr *name, int namelen);
16
17
18 DESCRIPTION
19 The parameter s is a socket. If it is of type SOCK_DGRAM, connect()
20 specifies the peer with which the socket is to be associated. This
21 address is the address to which datagrams are to be sent if a receiver
22 is not explicitly designated. This address is the only address from
23 which datagrams are to be received. If the socket s is of type
24 SOCK_STREAM, connect() attempts to make a connection to another socket.
25 The other socket is specified by name. name is an address in the
26 communication space of the socket. Each communication space interprets
27 the name parameter in its own way. If s is not bound, then s will be
28 bound to an address selected by the underlying transport provider.
29 Generally, stream sockets can successfully connect() only once.
30 Datagram sockets can use connect() multiple times to change their
31 association. Datagram sockets can dissolve the association by
32 connecting to a null address.
33
34 Non-blocking Sockets
35 When a socket is created, it is by default a blocking socket. A socket
36 may be configured to be non-blocking either at socket creation time or
37 through the use of fcntl(2). When a socket is set to be non-blocking, a
38 call to connect initiates an asynchronous connection. If the connection
39 cannot be completed without blocking, such as when making a TCP
40 connection to a remote server, then the connection attempt is made in
41 the background and connect returns -1 and errno is set to EINPROGRESS.
42
43 Applications can obtain the state of this connection attempt by polling
44 the socket's file descriptor for POLLOUT. The event ports facility is
45 the preferred means of polling on the file descriptor, see
46 port_create(3C) and port_get(3C) for more information on event ports;
47 however, applications may also use traditional portable routines like
48 poll(2) and select(3C).
49
50 When an asynchronous connection has completed, the application must
51 call getsockopt(3SOCKET) using the macro SOL_SOCKET as the level
52 argument and the macro SO_ERROR as the value of the option argument.
53 If the value of the SO_ERROR socket option is zero, then the connect
54 was successfully established. Otherwise, the connection could not be
55 established and the value is the corresponding error code that would be
56 commonly found in errno.
57
58 Even when a socket is in non-blocking mode, a call to connect may fail
59 synchronously. If any error other EINPROGRESS or EINTR occurs, then
60 there is no need for the application to poll for asynchronous
61 completion. Similarly, if a call to connect returns successfully, then
62 the socket connection will be established and there is no need to poll
63 for completion.
64
65 EXAMPLES
66 Example 1 Performing an asynchronous connection
67
68
69 The following sample C program shows how to create and connect to a
70 remote host using TCP. The program should be compiled and linked
71 against libnsl and libsocket. For example, if the contents of this
72 example where in a file called example.c, one would run cc example.c
73 -lnsl -lsocket.
74
75 #include <sys/types.h>
76 #include <sys/socket.h>
77 #include <netinet/in.h>
78 #include <arpa/inet.h>
79 #include <inttypes.h>
80 #include <stdio.h>
81 #include <strings.h>
82 #include <stdlib.h>
83 #include <errno.h>
84 #include <port.h>
85 #include <unistd.h>
86 #include <assert.h>
87
88 int
89 main(int argc, char *argv[])
90 {
91 char *eptr;
92 long port;
93 int sock, ret, eport;
94 struct sockaddr_in6 sin6;
95
96 if (argc != 3) {
97 fprintf(stderr, "connect: <IP> <port>\n");
98 return (1);
99 }
100
101 bzero(&sin6, sizeof (struct sockaddr_in6));
102 sin6.sin6_family = AF_INET6;
103
104 /*
105 * Try to parse as an IPv6 address and then try v4.
106 */
107 ret = inet_pton(AF_INET6, argv[1], &sin6.sin6_addr);
108 if (ret == -1) {
109 perror("inet_pton");
110 return (1);
111 } else if (ret == 0) {
112 struct in_addr v4;
113 ret = inet_pton(AF_INET, argv[1], &v4);
114 if (ret == -1) {
115 perror("inet_pton");
116 return (1);
117 } else if (ret == 0) {
118 fprintf(stderr, "connect: %s is not a valid "
119 "IPv4 or IPv6 address\n", argv[1]);
120 return (1);
121 }
122 /* N.B. Not a portable macro */
123 IN6_INADDR_TO_V4MAPPED(&v4, &sin6.sin6_addr);
124 }
125
126 errno = 0;
127 port = strtol(argv[2], &eptr, 10);
128 if (errno != 0 || *eptr != '\0') {
129 fprintf(stderr, "failed to parse port %s\n", argv[2]);
130 return (1);
131 }
132 if (port <= 0 || port > UINT16_MAX) {
133 fprintf(stderr, "invalid port: %ld\n", port);
134 return (1);
135 }
136 sin6.sin6_port = htons(port);
137
138 sock = socket(AF_INET6, SOCK_STREAM | SOCK_NONBLOCK, 0);
139 if (sock < 0) {
140 perror("socket");
141 return (1);
142 }
143
144 eport = port_create();
145 if (eport < 0) {
146 perror("port_create");
147 (void) close(sock);
148 return (1);
149 }
150
151 ret = connect(sock, (struct sockaddr *)&sin6,
152 sizeof (struct sockaddr_in6));
153 if (ret != 0 && errno != EINPROGRESS && errno != EINTR) {
154 perror("connect");
155 (void) close(sock);
156 (void) close(eport);
157 return (1);
158 }
159
160 if (ret != 0) {
161 port_event_t pe;
162 int err;
163 socklen_t sz = sizeof (err);
164 if (port_associate(eport, PORT_SOURCE_FD, sock, POLLOUT,
165 NULL) != 0) {
166 perror("port_associate");
167 (void) close(sock);
168 (void) close(eport);
169 return (1);
170 }
171 if (port_get(eport, &pe, NULL) != 0) {
172 perror("port_get");
173 (void) close(sock);
174 (void) close(eport);
175 return (1);
176 }
177 assert(pe.portev_source == PORT_SOURCE_FD);
178 assert(pe.portev_object == (uintptr_t)sock);
179 if (getsockopt(sock, SOL_SOCKET, SO_ERROR, &err, &sz) != 0) {
180 perror("getsockopt");
181 (void) close(sock);
182 (void) close(eport);
183 return (1);
184 }
185 if (err != 0) {
186 /* Asynch connect failed */
187 fprintf(stderr, "asynchronous connect: %s\n",
188 strerror(err));
189 (void) close(sock);
190 (void) close(eport);
191 return (1);
192 }
193 }
194
195 /* Read and write to the socket and then clean up */
196
197 return (0);
198 }
199
200 RETURN VALUES
201 If the connection or binding succeeds, 0 is returned. Otherwise, -1 is
202 returned and sets errno to indicate the error.
203
204 ERRORS
205 The call fails if:
206
207 EACCES
208 Search permission is denied for a component of the
209 path prefix of the pathname in name.
210
211
212 EADDRINUSE
213 The address is already in use.
214
215
216 EADDRNOTAVAIL
217 The specified address is not available on the remote
218 machine.
219
220
221 EAFNOSUPPORT
222 Addresses in the specified address family cannot be
223 used with this socket.
224
225
226 EALREADY
227 The socket is non-blocking, and a previous connection
228 attempt has not yet been completed.
229
230
231 EBADF
232 s is not a valid descriptor.
233
234
235 ECONNREFUSED
236 The attempt to connect was forcefully rejected. The
237 calling program should close(2) the socket descriptor,
238 and issue another socket(3SOCKET) call to obtain a new
239 descriptor before attempting another connect() call.
240
241
242 EINPROGRESS
243 The socket is non-blocking, and the connection cannot
244 be completed immediately. See the section on Non-
245 blocking Sockets for more information.
246
247
248 EINTR
249 The connection attempt was interrupted before any data
250 arrived by the delivery of a signal. The connection,
251 however, will be established asynchronously.
252
253
254 EINVAL
255 namelen is not the size of a valid address for the
256 specified address family.
257
258
259 EIO
260 An I/O error occurred while reading from or writing to
261 the file system.
262
263
264 EISCONN
265 The socket is already connected.
266
267
268 ELOOP
269 Too many symbolic links were encountered in
270 translating the pathname in name.
271
272
273 ENETUNREACH
274 The network is not reachable from this host.
275
276
277 EHOSTUNREACH
278 The remote host is not reachable from this host.
279
280
281 ENOENT
282 A component of the path prefix of the pathname in name
283 does not exist.
284
285
286 ENOENT
287 The socket referred to by the pathname in name does
288 not exist.
289
290
291 ENOSR
292 There were insufficient STREAMS resources available to
293 complete the operation.
294
295
296 ENXIO
297 The server exited before the connection was complete.
298
299
300 ETIMEDOUT
301 Connection establishment timed out without
302 establishing a connection.
303
304
305 EWOULDBLOCK
306 The socket is marked as non-blocking, and the
307 requested operation would block.
308
309
310
311 The following errors are specific to connecting names in the UNIX
312 domain. These errors might not apply in future versions of the UNIX
313 IPC domain.
314
315 ENOTDIR
316 A component of the path prefix of the pathname in name is
317 not a directory.
318
319
320 ENOTSOCK
321 s is not a socket.
322
323
324 ENOTSOCK
325 name is not a socket.
326
327
328 EPROTOTYPE
329 The file that is referred to by name is a socket of a
330 type other than type s. For example, s is a SOCK_DGRAM
331 socket, while name refers to a SOCK_STREAM socket.
332
333
334 ATTRIBUTES
335 See attributes(5) for descriptions of the following attributes:
336
337
338
339
340 +---------------+-----------------+
341 |ATTRIBUTE TYPE | ATTRIBUTE VALUE |
342 +---------------+-----------------+
343 |MT-Level | Safe |
344 +---------------+-----------------+
345
346 SEE ALSO
347 close(2), accept(3SOCKET), getsockname(3SOCKET), select(3C),
348 socket(3SOCKET), sockaddr(3SOCKET), socket.h(3HEAD), attributes(5)
349
350
351
352 November 25, 2014 CONNECT(3SOCKET)