connect()

initiate a connection on a socket 

Function


SYNOPSIS

#include <sys/types.h>

#include <sys/socket.h>

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


DESCRIPTION

The connect() system call initiates a connection on a socket. If the parameter s (a socket) is of type SOCK_DGRAM, then connect() permanently specifies the peer to which datagrams are to be sent. If s is of type SOCK_STREAM, then connect() attempts to make a connection to another socket. The name parameter specifies the other socket.

The connect() function is used to create a connection to the specified foreign association. The parameter s specifies an unconnected datagram or stream socket. If the socket is unbound, the system assigns unique values to the local association, and the socket is marked as bound.

For stream sockets (type SOCK_STREAM), an active connection is initiated to the foreign host using name (an address in the name space of the socket). When the socket call completes successfully, the socket is ready to send/receive data.

For a datagram socket (type SOCK_DGRAM), a default destination is set, which is used on subsequent send() and recv() calls.

If the connection cannot be established immediately and O_NONBLOCK is not set for the file descriptor for the socket, connect() blocks for up to an unspecified timeout interval until the connection is established. If the timeout interval expires before the connection is established, connect() fails and the connection attempt is aborted. If the connect() is interrupted by a signal that is caught while blocked waiting to establish a connection, connect() fails and sets errno to EINTR, but the connection request is not aborted, and the connection is established asynchronously.

If the connection cannot be established immediately and O_NONBLOCK is set for the file descriptor for the socket, connect() fails and sets errno to EINPROGRESS, but the connection request is not aborted, and the connection is established asynchronously. Subsequent calls to connect() for the same socket, before the connection is established, fails and sets errno to EALREADY.

When the connection has been established asynchronously, select() indicates that the file descriptor for the socket is ready for writing.


PARAMETERS

s 

Specifies the integer descriptor of the socket to be connected.

name 

Points to a sockaddr structure containing the peer address. The length and format of the address depend on the address family of the socket.

namelen 

Specifies the length of the sockaddr structure pointed to by name argument.


RETURN VALUES

If successful, connect() returns a value of zero. On failure, it returns -1 and sets errno to one of the following values. For a blocking socket, the return value indicates success or failure of the connection attempt.

EADDRINUSE 

The specified address is already in use.

EADDRNOTAVAIL 

The specified address is unavailable on the remote machine or the address field of the name structure is all zeroes.

EAFNOSUPPORT 

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

EALREADY 

A connection request is already in progress for the specified socket.

EBADF 

s is not a valid descriptor.

ECONNREFUSED 

The attempt to connect was forcefully rejected.

ECONNRESET 

The remote host reset the connection request.

EDESTADDREQ 

A destination address is required.

EFAULT 

name is an invalid pointer.

EHOSTUNREACH 

The destination host cannot be reached.

EINPROGRESS 

The socket is marked as non-blocking and the connection cannot be completed immediately. The connection is established asynchronously.

EINTR 

A signal interrupted the call. The connection is established asynchronously.

EINVAL 

The namelen argument is not a valid length for the address family, or the sockaddr structure contains an invalid address family.

EISCONN 

The socket is already connected.

EMFILE 

No more file descriptors are available.

ENETDOWN 

The network subsystem has failed.

ENETUNREACH 

The network is unreachable from this host at this time.

ENOBUFS 

No buffer space is available. The socket cannot be connected.

ENOTSOCK 

s is not a socket.

EOPNOTSUPP 

The socket is listening and cannot be connected.

ETIMEDOUT 

The attempt to connect timed out without establishing a connection.


CONFORMANCE

UNIX 98, with exceptions.


MULTITHREAD SAFETY LEVEL

MT-Safe.


PORTING ISSUES

The NuTCRACKER Platform supports all the address families that WinSock 2.0 supports.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Functions:
accept(), bind(), close(), getsockname(), select(), socket()


PTC MKS Toolkit 10.2 Documentation Build 28.