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"
11 connect \- initiate a connection on a socket
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);
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.
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
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
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.
70 \fBExample 1\fR Performing an asynchronous connection
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.
80 #include <sys/types.h>
81 #include <sys/socket.h>
82 #include <netinet/in.h>
83 #include <arpa/inet.h>
94 main(int argc, char *argv[])
99 struct sockaddr_in6 sin6;
102 fprintf(stderr, "connect: <IP> <port>\\n");
106 bzero(&sin6, sizeof (struct sockaddr_in6));
107 sin6.sin6_family = AF_INET6;
110 * Try to parse as an IPv6 address and then try v4.
112 ret = inet_pton(AF_INET6, argv[1], &sin6.sin6_addr);
116 } else if (ret == 0) {
118 ret = inet_pton(AF_INET, argv[1], &v4);
122 } else if (ret == 0) {
123 fprintf(stderr, "connect: %s is not a valid "
124 "IPv4 or IPv6 address\\n", argv[1]);
127 /* N.B. Not a portable macro */
128 IN6_INADDR_TO_V4MAPPED(&v4, &sin6.sin6_addr);
132 port = strtol(argv[2], &eptr, 10);
133 if (errno != 0 || *eptr != '\0') {
134 fprintf(stderr, "failed to parse port %s\\n", argv[2]);
137 if (port <= 0 || port > UINT16_MAX) {
138 fprintf(stderr, "invalid port: %ld\\n", port);
141 sin6.sin6_port = htons(port);
143 sock = socket(AF_INET6, SOCK_STREAM | SOCK_NONBLOCK, 0);
149 eport = port_create();
151 perror("port_create");
156 ret = connect(sock, (struct sockaddr *)&sin6,
157 sizeof (struct sockaddr_in6));
158 if (ret != 0 && errno != EINPROGRESS && errno != EINTR) {
168 socklen_t sz = sizeof (err);
169 if (port_associate(eport, PORT_SOURCE_FD, sock, POLLOUT,
171 perror("port_associate");
176 if (port_get(eport, &pe, NULL) != 0) {
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");
191 /* Asynch connect failed */
192 fprintf(stderr, "asnchronous connect: %s\\n",
200 /* Read and write to the socket and then clean up */
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.
219 Search permission is denied for a component of the path prefix of the pathname
226 \fB\fBEADDRINUSE\fR\fR
229 The address is already in use.
235 \fB\fBEADDRNOTAVAIL\fR\fR
238 The specified address is not available on the remote machine.
244 \fB\fBEAFNOSUPPORT\fR\fR
247 Addresses in the specified address family cannot be used with this socket.
256 The socket is non-blocking, and a previous connection attempt has not yet been
266 \fIs\fR is not a valid descriptor.
272 \fB\fBECONNREFUSED\fR\fR
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.
283 \fB\fBEINPROGRESS\fR\fR
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.
296 The connection attempt was interrupted before any data arrived by the delivery
297 of a signal. The connection, however, will be established asynchronously.
306 \fInamelen\fR is not the size of a valid address for the specified address
316 An I/O error occurred while reading from or writing to the file system.
325 The socket is already connected.
334 Too many symbolic links were encountered in translating the pathname in
341 \fB\fBENETUNREACH\fR\fR
344 The network is not reachable from this host.
350 \fB\fBEHOSTUNREACH\fR\fR
353 The remote host is not reachable from this host.
362 A component of the path prefix of the pathname in \fIname\fR does not exist.
371 The socket referred to by the pathname in \fIname\fR does not exist.
380 There were insufficient \fBSTREAMS\fR resources available to complete the
390 The server exited before the connection was complete.
396 \fB\fBETIMEDOUT\fR\fR
399 Connection establishment timed out without establishing a connection.
405 \fB\fBEWOULDBLOCK\fR\fR
408 The socket is marked as non-blocking, and the requested operation would block.
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.
421 A component of the path prefix of the pathname in \fIname\fR is not a
431 \fIs\fR is not a socket.
440 \fIname\fR is not a socket.
446 \fB\fBEPROTOTYPE\fR\fR
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.
456 See \fBattributes\fR(5) for descriptions of the following attributes:
464 ATTRIBUTE TYPE ATTRIBUTE VALUE
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)