man2/connect.2

   1 .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
   2 .\" Portions extracted from /usr/include/sys/socket.h, which does not have
   3 .\" any authorship information in it.  It is probably available under the GPL.
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .\"
   8 .\" Other portions are from the 6.9 (Berkeley) 3/10/91 man page:
   9 .\"
  10 .\" Copyright (c) 1983 The Regents of the University of California.
  11 .\" All rights reserved.
  12 .\"
  13 .\" SPDX-License-Identifier: BSD-4-Clause-UC
  14 .\"
  15 .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
  16 .\" Modified 1998, 1999 by Andi Kleen
  17 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
  18 .\"
  19 .TH CONNECT 2 2022-09-09 "Linux man-pages (unreleased)"
  20 .SH NAME
  21 connect \- initiate a connection on a socket
  22 .SH LIBRARY
  23 Standard C library
  24 .RI ( libc ", " \-lc )
  25 .SH SYNOPSIS
  26 .nf
  27 .B #include <sys/socket.h>
  28 .PP
  29 .BI "int connect(int " sockfd ", const struct sockaddr *" addr ,
  30 .BI "            socklen_t " addrlen );
  31 .fi
  32 .SH DESCRIPTION
  33 The
  34 .BR connect ()
  35 system call connects the socket referred to by the file descriptor
  36 .I sockfd
  37 to the address specified by
  38 .IR addr .
  39 The
  40 .I addrlen
  41 argument specifies the size of
  42 .IR addr .
  43 The format of the address in
  44 .I addr
  45 is determined by the address space of the socket
  46 .IR sockfd ;
  47 see
  48 .BR socket (2)
  49 for further details.
  50 .PP
  51 If the socket
  52 .I sockfd
  53 is of type
  54 .BR SOCK_DGRAM ,
  55 then
  56 .I addr
  57 is the address to which datagrams are sent by default, and the only
  58 address from which datagrams are received.
  59 If the socket is of type
  60 .B SOCK_STREAM
  61 or
  62 .BR SOCK_SEQPACKET ,
  63 this call attempts to make a connection to the socket that is bound
  64 to the address specified by
  65 .IR addr .
  66 .PP
  67 Some protocol sockets (e.g., UNIX domain stream sockets)
  68 may successfully
  69 .BR connect ()
  70 only once.
  71 .PP
  72 Some protocol sockets
  73 (e.g., datagram sockets in the UNIX and Internet domains)
  74 may use
  75 .BR connect ()
  76 multiple times to change their association.
  77 .PP
  78 Some protocol sockets
  79 (e.g., TCP sockets as well as datagram sockets in the UNIX and
  80 Internet domains)
  81 may dissolve the association by connecting to an address with the
  82 .I sa_family
  83 member of
  84 .I sockaddr
  85 set to
  86 .BR AF_UNSPEC ;
  87 thereafter, the socket can be connected to another address.
  88 .RB ( AF_UNSPEC
  89 is supported on Linux since kernel 2.2.)
  90 .SH RETURN VALUE
  91 If the connection or binding succeeds, zero is returned.
  92 On error, \-1 is returned, and
  93 .I errno
  94 is set to indicate the error.
  95 .SH ERRORS
  96 The following are general socket errors only.
  97 There may be other domain-specific error codes.
  98 .TP
  99 .B EACCES
 100 For UNIX domain sockets, which are identified by pathname:
 101 Write permission is denied on the socket file,
 102 or search permission is denied for one of the directories
 103 in the path prefix.
 104 (See also
 105 .BR path_resolution (7).)
 106 .TP
 107 .BR EACCES ", " EPERM
 108 The user tried to connect to a broadcast address without having the socket
 109 broadcast flag enabled or the connection request failed because of a local
 110 firewall rule.
 111 .IP
 112 .B EACCES
 113 can also be returned if an SELinux policy denied a connection (for
 114 example, if there is a policy saying that an HTTP proxy can only
 115 connect to ports associated with HTTP servers, and the proxy tries to
 116 connect to a different port).
 117 dd
 118 .TP
 119 .B EADDRINUSE
 120 Local address is already in use.
 121 .TP
 122 .B EADDRNOTAVAIL
 123 (Internet domain sockets)
 124 The socket referred to by
 125 .I sockfd
 126 had not previously been bound to an address and,
 127 upon attempting to bind it to an ephemeral port,
 128 it was determined that all port numbers in the ephemeral port range
 129 are currently in use.
 130 See the discussion of
 131 .I /proc/sys/net/ipv4/ip_local_port_range
 132 in
 133 .BR ip (7).
 134 .TP
 135 .B EAFNOSUPPORT
 136 The passed address didn't have the correct address family in its
 137 .I sa_family
 138 field.
 139 .TP
 140 .B EAGAIN
 141 For nonblocking UNIX domain sockets, the socket is nonblocking, and the
 142 connection cannot be completed immediately.
 143 For other socket families, there are insufficient entries in the routing cache.
 144 .TP
 145 .B EALREADY
 146 The socket is nonblocking and a previous connection attempt has not yet
 147 been completed.
 148 .TP
 149 .B EBADF
 150 .I sockfd
 151 is not a valid open file descriptor.
 152 .TP
 153 .B ECONNREFUSED
 154 A
 155 .BR connect ()
 156 on a stream socket found no one listening on the remote address.
 157 .TP
 158 .B EFAULT
 159 The socket structure address is outside the user's address space.
 160 .TP
 161 .B EINPROGRESS
 162 The socket is nonblocking and the connection cannot be completed immediately.
 163 (UNIX domain sockets failed with
 164 .B EAGAIN
 165 instead.)
 166 It is possible to
 167 .BR select (2)
 168 or
 169 .BR poll (2)
 170 for completion by selecting the socket for writing.
 171 After
 172 .BR select (2)
 173 indicates writability, use
 174 .BR getsockopt (2)
 175 to read the
 176 .B SO_ERROR
 177 option at level
 178 .B SOL_SOCKET
 179 to determine whether
 180 .BR connect ()
 181 completed successfully
 182 .RB ( SO_ERROR
 183 is zero) or unsuccessfully
 184 .RB ( SO_ERROR
 185 is one of the usual error codes listed here,
 186 explaining the reason for the failure).
 187 .TP
 188 .B EINTR
 189 The system call was interrupted by a signal that was caught; see
 190 .BR signal (7).
 191 .\" For TCP, the connection will complete asynchronously.
 192 .\" See http://lkml.org/lkml/2005/7/12/254
 193 .TP
 194 .B EISCONN
 195 The socket is already connected.
 196 .TP
 197 .B ENETUNREACH
 198 Network is unreachable.
 199 .TP
 200 .B ENOTSOCK
 201 The file descriptor
 202 .I sockfd
 203 does not refer to a socket.
 204 .TP
 205 .B EPROTOTYPE
 206 The socket type does not support the requested communications protocol.
 207 This error can occur, for example,
 208 on an attempt to connect a UNIX domain datagram socket to a stream socket.
 209 .TP
 210 .B ETIMEDOUT
 211 Timeout while attempting connection.
 212 The server may be too
 213 busy to accept new connections.
 214 Note that for IP sockets the timeout may
 215 be very long when syncookies are enabled on the server.
 216 .SH STANDARDS
 217 POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD,
 218 .RB (connect ()
 219 first appeared in 4.2BSD).
 220 .\" SVr4 documents the additional
 221 .\" general error codes
 222 .\" .BR EADDRNOTAVAIL ,
 223 .\" .BR EINVAL ,
 224 .\" .BR EAFNOSUPPORT ,
 225 .\" .BR EALREADY ,
 226 .\" .BR EINTR ,
 227 .\" .BR EPROTOTYPE ,
 228 .\" and
 229 .\" .BR ENOSR .
 230 .\" It also
 231 .\" documents many additional error conditions not described here.
 232 .SH NOTES
 233 For background on the
 234 .I socklen_t
 235 type, see
 236 .BR accept (2).
 237 .PP
 238 If
 239 .BR connect ()
 240 fails, consider the state of the socket as unspecified.
 241 Portable applications should close the socket and create a new one for
 242 reconnecting.
 243 .SH EXAMPLES
 244 An example of the use of
 245 .BR connect ()
 246 is shown in
 247 .BR getaddrinfo (3).
 248 .SH SEE ALSO
 249 .BR accept (2),
 250 .BR bind (2),
 251 .BR getsockname (2),
 252 .BR listen (2),
 253 .BR socket (2),
 254 .BR path_resolution (7),
 255 .BR selinux (8)