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>
  18 
  19 
  20 
  21 \fBint\fR \fBconnect\fR(\fBint\fR \fIs\fR, \fBconst struct sockaddr *\fR\fIname\fR, \fBint\fR \fInamelen\fR);
  22 .fi
  23 
  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>
  92 
  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;
 100 
 101         if (argc != 3) {
 102                 fprintf(stderr, "connect: <IP> <port>\\n");
 103                 return (1);
 104         }
 105 
 106         bzero(&sin6, sizeof (struct sockaddr_in6));
 107         sin6.sin6_family = AF_INET6;
 108 
 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         }
 130 
 131         errno = 0;
 132         port = strtol(argv[2], &eptr, 10);
 133         if (errno != 0 || *eptr != '\e0') {
 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);
 142 
 143         sock = socket(AF_INET6, SOCK_STREAM | SOCK_NONBLOCK, 0);
 144         if (sock < 0) {
 145                 perror("socket");
 146                 return (1);
 147         }
 148 
 149         eport = port_create();
 150         if (eport < 0) {
 151                 perror("port_create");
 152                 (void) close(sock);
 153                 return (1);
 154         }
 155 
 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         }
 164 
 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, "asynchronous connect: %s\\n",
 193                             strerror(err));
 194                         (void) close(sock);
 195                         (void) close(eport);
 196                         return (1);
 197                 }
 198         }
 199 
 200         /* Read and write to the socket and then clean up */
 201 
 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
 222 
 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
 231 
 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
 240 
 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
 249 
 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
 259 
 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
 268 
 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
 279 
 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
 289 
 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
 299 
 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
 309 
 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
 318 
 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
 327 
 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
 337 
 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
 346 
 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
 355 
 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
 364 
 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
 373 
 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
 383 
 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
 392 
 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
 401 
 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
 410 
 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
 424 
 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
 433 
 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
 442 
 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
 453 
 454 .SH ATTRIBUTES
 455 .LP
 456 See \fBattributes\fR(5) for descriptions of the following attributes:
 457 .sp
 458 
 459 .sp
 460 .TS
 461 box;
 462 c | c
 463 l | l .
 464 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 465 _
 466 MT-Level        Safe
 467 .TE
 468 
 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)