| blob | 7da31cd712ca550024fac0dd9cdb6c17acbd0527 |
1 '\" te
2 .\" Copyright (C) 2005, Sun Microsystems, Inc.
3 .\" All Rights Reserved
4 .\" Copyright (c) 2014, Joyent, Inc.
5 .\" Copyright 1989 AT&T All Rights Reserved
6 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
7 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
8 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
9 .TH CONNECT 3SOCKET "Nov 25, 2014"
10 .SH NAME
11 connect \- initiate a connection on a socket
12 .SH SYNOPSIS
13 .LP
14 .nf
15 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ]
16 #include <sys/types.h>
17 #include <sys/socket.h>
21 \fBint\fR \fBconnect\fR(\fBint\fR \fIs\fR, \fBconst struct sockaddr *\fR\fIname\fR, \fBint\fR \fInamelen\fR);
22 .fi
24 .SH DESCRIPTION
25 .LP
26 The parameter \fIs\fR is a socket. If it is of type \fBSOCK_DGRAM\fR,
27 \fBconnect()\fR specifies the peer with which the socket is to be associated.
28 This address is the address to which datagrams are to be sent if a receiver is
29 not explicitly designated. This address is the only address from which
30 datagrams are to be received. If the socket \fIs\fR is of type
31 \fBSOCK_STREAM\fR, \fBconnect()\fR attempts to make a connection to another
32 socket. The other socket is specified by \fIname\fR. \fIname\fR is an address
33 in the communication space of the socket. Each communication space interprets
34 the \fIname\fR parameter in its own way. If \fIs\fR is not bound, then \fIs\fR
35 will be bound to an address selected by the underlying transport provider.
36 Generally, stream sockets can successfully \fBconnect()\fR only once. Datagram
37 sockets can use \fBconnect()\fR multiple times to change their association.
38 Datagram sockets can dissolve the association by connecting to a null address.
39 .SS Non-blocking Sockets
40 When a socket is created, it is by default a \fBblocking\fR socket. A socket may
41 be configured to be \fBnon-blocking\fR either at socket creation time or through
42 the use of \fBfcntl\fR(2). When a socket is set to be \fBnon-blocking\fR, a call
43 to connect initiates an asynchronous connection. If the connection cannot be
44 completed without blocking, such as when making a TCP connection to a remote
45 server, then the connection attempt is made in the background and \fBconnect\fR
46 returns -1 and errno is set to \fBEINPROGRESS\fR.
47 .LP
48 Applications can obtain the state of this connection attempt by polling the
49 socket's file descriptor for \fBPOLLOUT\fR. The event ports facility is the
50 preferred means of polling on the file descriptor, see \fBport_create\fR(3C) and
51 \fBport_get\fR(3C) for more information on event ports; however, applications
52 may also use traditional portable routines like \fBpoll\fR(2) and
53 \fBselect\fR(3C).
54 .LP
55 When an asynchronous connection has completed, the application must call
56 \fBgetsockopt\fR(3SOCKET) using the macro \fBSOL_SOCKET\fR as the \fIlevel\fR
57 argument and the macro \fBSO_ERROR\fR as the value of the \fIoption\fR argument.
58 If the value of the \fBSO_ERROR\fR socket option is zero, then the
59 connect was successfully established. Otherwise, the connection could not be
60 established and the value is the corresponding error code that would be commonly
61 found in \fBerrno\fR.
62 .LP
63 Even when a socket is in \fBnon-blocking\fR mode, a call to \fBconnect\fR may
64 fail synchronously. If any error other \fBEINPROGRESS\fR or \fBEINTR\fR occurs,
65 then there is no need for the application to poll for asynchronous completion.
66 Similarly, if a call to \fBconnect\fR returns successfully, then the socket
67 connection will be established and there is no need to poll for completion.
68 .SH EXAMPLES
69 .LP
70 \fBExample 1\fR Performing an asynchronous connection
71 .sp
72 .LP
73 The following sample C program shows how to create and connect to a remote host
74 using TCP. The program should be compiled and linked against libnsl and
75 libsocket. For example, if the contents of this example where in a file called
76 example.c, one would run cc example.c -lnsl -lsocket.
77 .sp
78 .in +2
79 .nf
80 #include <sys/types.h>
81 #include <sys/socket.h>
82 #include <netinet/in.h>
83 #include <arpa/inet.h>
84 #include <inttypes.h>
85 #include <stdio.h>
86 #include <strings.h>
87 #include <stdlib.h>
88 #include <errno.h>
89 #include <port.h>
90 #include <unistd.h>
91 #include <assert.h>
93 int
94 main(int argc, char *argv[])
95 {
96 char *eptr;
97 long port;
98 int sock, ret, eport;
99 struct sockaddr_in6 sin6;
101 if (argc != 3) {
102 fprintf(stderr, "connect: <IP> <port>\\n");
103 return (1);
104 }
106 bzero(&sin6, sizeof (struct sockaddr_in6));
107 sin6.sin6_family = AF_INET6;
109 /*
110 * Try to parse as an IPv6 address and then try v4.
111 */
112 ret = inet_pton(AF_INET6, argv[1], &sin6.sin6_addr);
113 if (ret == -1) {
114 perror("inet_pton");
115 return (1);
116 } else if (ret == 0) {
117 struct in_addr v4;
118 ret = inet_pton(AF_INET, argv[1], &v4);
119 if (ret == -1) {
120 perror("inet_pton");
121 return (1);
122 } else if (ret == 0) {
123 fprintf(stderr, "connect: %s is not a valid "
124 "IPv4 or IPv6 address\\n", argv[1]);
125 return (1);
126 }
127 /* N.B. Not a portable macro */
128 IN6_INADDR_TO_V4MAPPED(&v4, &sin6.sin6_addr);
129 }
131 errno = 0;
132 port = strtol(argv[2], &eptr, 10);
133 if (errno != 0 || *eptr != '\0') {
134 fprintf(stderr, "failed to parse port %s\\n", argv[2]);
135 return (1);
136 }
137 if (port <= 0 || port > UINT16_MAX) {
138 fprintf(stderr, "invalid port: %ld\\n", port);
139 return (1);
140 }
141 sin6.sin6_port = htons(port);
143 sock = socket(AF_INET6, SOCK_STREAM | SOCK_NONBLOCK, 0);
144 if (sock < 0) {
145 perror("socket");
146 return (1);
147 }
149 eport = port_create();
150 if (eport < 0) {
151 perror("port_create");
152 (void) close(sock);
153 return (1);
154 }
156 ret = connect(sock, (struct sockaddr *)&sin6,
157 sizeof (struct sockaddr_in6));
158 if (ret != 0 && errno != EINPROGRESS && errno != EINTR) {
159 perror("connect");
160 (void) close(sock);
161 (void) close(eport);
162 return (1);
163 }
165 if (ret != 0) {
166 port_event_t pe;
167 int err;
168 socklen_t sz = sizeof (err);
169 if (port_associate(eport, PORT_SOURCE_FD, sock, POLLOUT,
170 NULL) != 0) {
171 perror("port_associate");
172 (void) close(sock);
173 (void) close(eport);
174 return (1);
175 }
176 if (port_get(eport, &pe, NULL) != 0) {
177 perror("port_get");
178 (void) close(sock);
179 (void) close(eport);
180 return (1);
181 }
182 assert(pe.portev_source == PORT_SOURCE_FD);
183 assert(pe.portev_object == (uintptr_t)sock);
184 if (getsockopt(sock, SOL_SOCKET, SO_ERROR, &err, &sz) != 0) {
185 perror("getsockopt");
186 (void) close(sock);
187 (void) close(eport);
188 return (1);
189 }
190 if (err != 0) {
191 /* Asynch connect failed */
192 fprintf(stderr, "asnchronous connect: %s\\n",
193 strerror(err));
194 (void) close(sock);
195 (void) close(eport);
196 return (1);
197 }
198 }
200 /* Read and write to the socket and then clean up */
202 return (0);
203 }
204 .fi
205 .in -2
206 .SH RETURN VALUES
207 .LP
208 If the connection or binding succeeds, \fB0\fR is returned. Otherwise,
209 \fB\(mi1\fR is returned and sets \fBerrno\fR to indicate the error.
210 .SH ERRORS
211 .LP
212 The call fails if:
213 .sp
214 .ne 2
215 .na
216 \fB\fBEACCES\fR\fR
217 .ad
218 .RS 17n
219 Search permission is denied for a component of the path prefix of the pathname
220 in \fIname\fR.
221 .RE
223 .sp
224 .ne 2
225 .na
226 \fB\fBEADDRINUSE\fR\fR
227 .ad
228 .RS 17n
229 The address is already in use.
230 .RE
232 .sp
233 .ne 2
234 .na
235 \fB\fBEADDRNOTAVAIL\fR\fR
236 .ad
237 .RS 17n
238 The specified address is not available on the remote machine.
239 .RE
241 .sp
242 .ne 2
243 .na
244 \fB\fBEAFNOSUPPORT\fR\fR
245 .ad
246 .RS 17n
247 Addresses in the specified address family cannot be used with this socket.
248 .RE
250 .sp
251 .ne 2
252 .na
253 \fB\fBEALREADY\fR\fR
254 .ad
255 .RS 17n
256 The socket is non-blocking, and a previous connection attempt has not yet been
257 completed.
258 .RE
260 .sp
261 .ne 2
262 .na
263 \fB\fBEBADF\fR\fR
264 .ad
265 .RS 17n
266 \fIs\fR is not a valid descriptor.
267 .RE
269 .sp
270 .ne 2
271 .na
272 \fB\fBECONNREFUSED\fR\fR
273 .ad
274 .RS 17n
275 The attempt to connect was forcefully rejected. The calling program should
276 \fBclose\fR(2) the socket descriptor, and issue another \fBsocket\fR(3SOCKET)
277 call to obtain a new descriptor before attempting another \fBconnect()\fR call.
278 .RE
280 .sp
281 .ne 2
282 .na
283 \fB\fBEINPROGRESS\fR\fR
284 .ad
285 .RS 17n
286 The socket is non-blocking, and the connection cannot be completed immediately.
287 See the section on \fBNon-blocking Sockets\fR for more information.
288 .RE
290 .sp
291 .ne 2
292 .na
293 \fB\fBEINTR\fR\fR
294 .ad
295 .RS 17n
296 The connection attempt was interrupted before any data arrived by the delivery
297 of a signal. The connection, however, will be established asynchronously.
298 .RE
300 .sp
301 .ne 2
302 .na
303 \fB\fBEINVAL\fR\fR
304 .ad
305 .RS 17n
306 \fInamelen\fR is not the size of a valid address for the specified address
307 family.
308 .RE
310 .sp
311 .ne 2
312 .na
313 \fB\fBEIO\fR\fR
314 .ad
315 .RS 17n
316 An I/O error occurred while reading from or writing to the file system.
317 .RE
319 .sp
320 .ne 2
321 .na
322 \fB\fBEISCONN\fR\fR
323 .ad
324 .RS 17n
325 The socket is already connected.
326 .RE
328 .sp
329 .ne 2
330 .na
331 \fB\fBELOOP\fR\fR
332 .ad
333 .RS 17n
334 Too many symbolic links were encountered in translating the pathname in
335 \fIname\fR.
336 .RE
338 .sp
339 .ne 2
340 .na
341 \fB\fBENETUNREACH\fR\fR
342 .ad
343 .RS 17n
344 The network is not reachable from this host.
345 .RE
347 .sp
348 .ne 2
349 .na
350 \fB\fBEHOSTUNREACH\fR\fR
351 .ad
352 .RS 17n
353 The remote host is not reachable from this host.
354 .RE
356 .sp
357 .ne 2
358 .na
359 \fB\fBENOENT\fR\fR
360 .ad
361 .RS 17n
362 A component of the path prefix of the pathname in \fIname\fR does not exist.
363 .RE
365 .sp
366 .ne 2
367 .na
368 \fB\fBENOENT\fR\fR
369 .ad
370 .RS 17n
371 The socket referred to by the pathname in \fIname\fR does not exist.
372 .RE
374 .sp
375 .ne 2
376 .na
377 \fB\fBENOSR\fR\fR
378 .ad
379 .RS 17n
380 There were insufficient \fBSTREAMS\fR resources available to complete the
381 operation.
382 .RE
384 .sp
385 .ne 2
386 .na
387 \fB\fBENXIO\fR\fR
388 .ad
389 .RS 17n
390 The server exited before the connection was complete.
391 .RE
393 .sp
394 .ne 2
395 .na
396 \fB\fBETIMEDOUT\fR\fR
397 .ad
398 .RS 17n
399 Connection establishment timed out without establishing a connection.
400 .RE
402 .sp
403 .ne 2
404 .na
405 \fB\fBEWOULDBLOCK\fR\fR
406 .ad
407 .RS 17n
408 The socket is marked as non-blocking, and the requested operation would block.
409 .RE
411 .sp
412 .LP
413 The following errors are specific to connecting names in the UNIX domain.
414 These errors might not apply in future versions of the UNIX \fBIPC\fR domain.
415 .sp
416 .ne 2
417 .na
418 \fB\fBENOTDIR\fR\fR
419 .ad
420 .RS 14n
421 A component of the path prefix of the pathname in \fIname\fR is not a
422 directory.
423 .RE
425 .sp
426 .ne 2
427 .na
428 \fB\fBENOTSOCK\fR\fR
429 .ad
430 .RS 14n
431 \fIs\fR is not a socket.
432 .RE
434 .sp
435 .ne 2
436 .na
437 \fB\fBENOTSOCK\fR\fR
438 .ad
439 .RS 14n
440 \fIname\fR is not a socket.
441 .RE
443 .sp
444 .ne 2
445 .na
446 \fB\fBEPROTOTYPE\fR\fR
447 .ad
448 .RS 14n
449 The file that is referred to by \fIname\fR is a socket of a type other than
450 type \fIs\fR. For example, \fIs\fR is a \fBSOCK_DGRAM\fR socket, while
451 \fIname\fR refers to a \fBSOCK_STREAM\fR socket.
452 .RE
454 .SH ATTRIBUTES
455 .LP
456 See \fBattributes\fR(5) for descriptions of the following attributes:
457 .sp
459 .sp
460 .TS
461 box;
462 c | c
463 l | l .
464 ATTRIBUTE TYPE ATTRIBUTE VALUE
465 _
466 MT-Level Safe
467 .TE
469 .SH SEE ALSO
470 .LP
471 \fBclose\fR(2), \fBaccept\fR(3SOCKET), \fBgetsockname\fR(3SOCKET),
472 \fBselect\fR(3C), \fBsocket\fR(3SOCKET), \fBsockaddr\fR(3SOCKET),
473 \fBsocket.h\fR(3HEAD), \fBattributes\fR(5)