connect(3)

NAME
connect - initiate a connection on a socket

SYNOPSIS
#include <sys/socket.h>

  AF_UNIX only:
#include <sys/un.h>

int connect(int s, struct sockaddr *addr, size_t addrlen);

DESCRIPTION
The parameter s is a socket descriptor. addr is a pointer to a socket address structure. This structure contains the address of a remote socket to which a connection will be established. addrlen is the size of this address structure. Since the size of the socket address structure varies among socket address families, the correct socket address structure should be used with each address family (for example, struct sockaddr_un for AF_UNIX). Typically, the sizeof function is used to pass this value (for example, sizeof(struct sockaddr_un)).

If the socket is of type SOCK_DGRAM, connect specifies the peer address to which messages are to be sent, and the call returns immediately. Furthermore, this socket can only receive messages sent from this address.

If the socket is of type SOCK_STREAM, connect attempts to contact the remote host in order to make a connection between the remote socket (peer) and the local socket specified by s. The call normally blocks until the connection completes. If non-blocking mode has been enabled using the O_NDELAY fcntl flag and the connection cannot be completed immediately, connect returns an error as described below. In these cases, select(3) can be used on this socket to determine when the connection has completed by selecting it for writing.

O_NDELAY is defined in <fcntl.h>.

Generally, stream sockets may successfully connect only once; datagram sockets may use connect multiple times to change the peer address. For datagram sockets, a side effect of attempting to connect to some invalid address (see DIAGNOSTICS below) is that the peer address is no longer maintained by the system. An example of an invalid address for a datagram socket is addrlen set to 0 and addr set to any value. If you set the address family of the destination socket to AF_UNSPEC, this is an invalid address, too.

RETURN VALUE
If the call is successful, 0 is returned. If it fails, -1 is returned and an error code is stored in errno.

DIAGNOSTICS
connect fails if:

[EBADF]
    s is not a valid file descriptor.

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

    For datagram sockets, the peer address is no longer maintained by the system.

[EALREADY]
    Non-blocking I/O is enabled using O_NDELAY and a previous connection attempt has not yet completed.

[EISCONN]
    The socket is already connected.

[EINVAL]
    The socket has already been shut down, has a listen active on it or addrlen is a bad value.

    For datagram sockets, if addrlen is a bad value, the peer address is no longer maintained by the system. s is a file descriptor for a file, not a socket.

[ETIMEDOUT]
    Connection establishment timed out without establishing a connection. backlog may be full (see listen(3)).

[ECONNREFUSED]
    The attempt to connect was forcefully rejected.

[EDESTADDRREQ]
    addr is a NULL pointer.

[EINPROGRESS]
    Non-blocking I/O is enabled using O_NDELAY and the connection cannot be completed immediately. This is not a failure. Make the connect(3) call again a few seconds later. Alternatively, wait for completion by calling select(3), selecting for write.

[EINTR]
    The connect was interrupted by delivery of a signal before the connect sequence was complete. The building of the connection still takes place, even though the user is not blocked on the connect call.

[EOPNOTSUPP]
    A connect attempt was made on a socket type which does not support this call.

SEE ALSO
accept(3), select(3), socket(3), getsockname(3).