Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CONNECT(2)		  FreeBSD System Calls Manual		    CONNECT(2)

NAME
     connect --	initiate a connection on a socket

SYNOPSIS
     #include <sys/socket.h>

     int
     connect(int s, const struct sockaddr *name, socklen_t namelen);

DESCRIPTION
     The parameter s is	a socket.  If it is of type SOCK_DGRAM,	this call
     specifies the peer	with which the socket is to be associated; this	ad-
     dress is that to which datagrams are to be	sent, and the only address
     from which	datagrams are to be received.  If the socket is	of type
     SOCK_STREAM, this call attempts to	make a connection to another socket.
     The other socket is specified by name, which is an	address	in the commu-
     nications space of	the socket.  namelen indicates the amount of space
     pointed to	by name, in bytes; the sa_len member of	name is	ignored.  Each
     communications space interprets the name parameter	in its own way.	 Gen-
     erally, stream sockets may	use connect() only once; datagram sockets may
     use connect() multiple times to change their association.	Datagram sock-
     ets may dissolve the association by connecting to an invalid address,
     such as a null address.

     If	the socket is in non-blocking mode and the connection cannot be	com-
     pleted immediately, or if it is interrupted by a signal, connect()	will
     return an error and the connection	attempt	will proceed asynchronously.
     Subsequent	calls to connect() will	fail with errno	set to EALREADY.  It
     is	possible to use	select(2) or poll(2) to	determine when the connect op-
     eration has completed by checking the socket for writability.  The	suc-
     cess or failure of	the connection attempt may be determined by using
     getsockopt(2) to check the	socket error status with the SO_ERROR option
     at	the SOL_SOCKET level.  If the connection was successful, the error
     value will	be zero.  Otherwise, it	will be	one of the error values	listed
     below.

RETURN VALUES
     If	the connection or binding succeeds, 0 is returned.  Otherwise a	-1 is
     returned, and a more specific error code is stored	in errno.

EXAMPLES
     The following code	connects to the	host described by name and handles the
     case where	connect() is interrupted by a signal.

	   #include <sys/socket.h>
	   #include <poll.h>
	   #include <errno.h>
	   #include <err.h>

	   int
	   connect_wait(int s)
	   {
		   struct pollfd pfd[1];
		   int error = 0;
		   socklen_t len = sizeof(error);

		   pfd[0].fd = s;
		   pfd[0].events = POLLOUT;

		   if (poll(pfd, 1, -1)	== -1)
			   return -1;
		   if (getsockopt(s, SOL_SOCKET, SO_ERROR, &error, &len) == -1)
			   return -1;
		   if (error !=	0) {
			   errno = error;
			   return -1;
		   }
		   return 0;
	   }

	   ...

	   int retcode;

	   ...

	   for (retcode	= connect(s, name, namelen);
	       retcode == -1 &&	errno == EINTR;
	       retcode = connect_wait(s))
		   continue;
	   if (retcode == -1)
		   err(1, "connect");

ERRORS
     The connect() call	fails if:

     [EBADF]		s is not a valid descriptor.

     [ENOTSOCK]		s is not a socket.

     [EADDRNOTAVAIL]	No suitable address is available on the	local machine.

     [EAFNOSUPPORT]	Addresses in the specified address family cannot be
			used with this socket.

     [EISCONN]		The socket is already connected.

     [ETIMEDOUT]	Connection establishment timed out without establish-
			ing a connection.

     [EINVAL]		A TCP connection with a	local broadcast, the all-ones
			or a multicast address as the peer was attempted.

     [ECONNREFUSED]	The attempt to connect was forcefully rejected.

     [EHOSTUNREACH]	The destination	address	specified an unreachable host.

     [EINTR]		The connection attempt was interrupted by a signal.
			The attempt will continue asynchronously as if the
			socket was non-blocking.

     [ENETUNREACH]	The network isn't reachable from this host.

     [EADDRINUSE]	The address is already in use.

     [EFAULT]		The name parameter specifies an	area outside the
			process	address	space.

     [EINPROGRESS]	The socket is non-blocking and the connection cannot
			be completed immediately.

     [EALREADY]		Either the socket is non-blocking or a previous	call
			to connect() was interrupted by	a signal, and the con-
			nection	attempt	has not	yet been completed.

     [EPERM]		A TCP connection on a socket with socket option
			TCP_MD5SIG was attempted without configuring the secu-
			rity parameters	correctly.

     The following errors are specific to connecting names in the UNIX-domain.
     These errors may not apply	in future versions of the UNIX IPC domain.

     [ENOTDIR]		A component of the path	prefix is not a	directory.

     [ENAMETOOLONG]	A component of a pathname exceeded NAME_MAX charac-
			ters, or an entire pathname (including the terminating
			NUL) exceeded PATH_MAX bytes.

     [ENOENT]		The named socket does not exist.

     [EACCES]		Search permission is denied for	a component of the
			path prefix.

     [EACCES]		Write access to	the named socket is denied.

     [ELOOP]		Too many symbolic links	were encountered in translat-
			ing the	pathname.

     [EPROTOTYPE]	The file described by name is of a different type than
			s.  E.g., s may	be of type SOCK_STREAM whereas name
			may refer to a socket of type SOCK_DGRAM.

SEE ALSO
     accept(2),	getsockname(2),	getsockopt(2), poll(2),	select(2), socket(2)

STANDARDS
     The connect() function conforms to	IEEE Std 1003.1-2008 ("POSIX.1").

HISTORY
     The connect() system call first appeared in 4.1cBSD.

FreeBSD	13.0			 June 20, 2019			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | ERRORS | SEE ALSO | STANDARDS | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=connect&sektion=2&manpath=OpenBSD+6.9>

home | help